Getting Started

The instructions below cover both Scala 2 and Scala 3.

Resources For Newcomers

Install Scala on your computer

Installing Scala means installing various command-line tools such as the Scala compiler and build tools. We recommend using the Scala installer tool “Coursier” that automatically installs all the requirements, but you can still manually install each tool.

Using the Scala Installer (recommended way)

The Scala installer is a tool named Coursier, whose main command is named cs. It ensures that a JVM and standard Scala tools are installed on your system. Install it on your system with the following instructions.

brew install coursier && coursier setup

curl -fL https://github.com/VirtusLab/coursier-m1/releases/latest/download/cs-aarch64-apple-darwin.gz | gzip -d > cs && chmod +x cs && (xattr -d com.apple.quarantine cs || true) && ./cs setup

curl -fL https://github.com/coursier/coursier/releases/latest/download/cs-x86_64-apple-darwin.gz | gzip -d > cs && chmod +x cs && (xattr -d com.apple.quarantine cs || true) && ./cs setup

curl -fL https://github.com/coursier/coursier/releases/latest/download/cs-x86_64-pc-linux.gz | gzip -d > cs && chmod +x cs && ./cs setup

curl -fL https://github.com/VirtusLab/coursier-m1/releases/latest/download/cs-aarch64-pc-linux.gz | gzip -d > cs && chmod +x cs && ./cs setup

   You may need to restart your terminal, log out, or reboot in order for the changes to take effect.

$ scala -version
Scala code runner version: 1.4.3
Scala version (default): 3.5.2

Along with managing JVMs, cs setup also installs useful command-line tools:

For more information about cs, read coursier-cli documentation.

cs setup installs the Scala 3 compiler and runner by default (the scalac and scala commands, respectively). Whether you intend to use Scala 2 or 3, this is usually not an issue because most projects use a build tool that will use the correct version of Scala irrespective of the one installed “globally”. Nevertheless, you can always launch a specific version of Scala using

$ cs launch scala:2.13.15
$ cs launch scalac:2.13.15

If you prefer Scala 2 to be run by default, you can force that version to be installed with:

$ cs install scala:2.13.15 scalac:2.13.15

…or manually

You only need two tools to compile, run, test, and package a Scala project: Java 8 or 11, and Scala CLI. To install them manually:

1. if you don’t have Java 8 or 11 installed, download Java from Oracle Java 8, Oracle Java 11, or AdoptOpenJDK 8/11. Refer to JDK Compatibility for Scala/Java compatibility detail.
2. Install Scala CLI

Using the Scala CLI

In a directory of your choice, which we will call <project-dir>, create a file named hello.scala with the following code:

//> using scala 3.5.2

@main
def hello(): Unit =
  println("Hello, World!")

You can define a method with the def keyword and mark it as a “main” method with the @main annotation, designating it as the entry point in program execution. The method’s type is Unit, which means it does not return a value. Unit can be thought of as an analogue to the void keyword found in other languages. The println method will print the "Hello, World!" string to standard output.

To run the program, execute scala run hello.scala command from a terminal, within the <project-dir> directory. The file will be compiled and executed, with console output similar to following:

$ scala run hello.scala
Compiling project (Scala 3.5.2, JVM (20))
Compiled project (Scala 3.5.2, JVM (20))
Hello, World!

Handling command-line arguments

Rewrite the hello.scala file so that the program greets the person running it.

//> using scala 3.5.2

@main
def hello(name: String): Unit =
  println(s"Hello, $name!")

The name argument is expected to be provided when executing the program, and if it’s not found, the execution will fail. The println method receives an interpolated string, as indicated by the s letter preceding its content. $name will be substituted by the content of the name argument.

To pass the arguments when executing the program, put them after --:

$ scala run hello.scala -- Gabriel
Compiling project (Scala 3.5.2, JVM (20))
Compiled project (Scala 3.5.2, JVM (20))
Hello, Gabriel!

You can read more about main methods and string interpolation in the Scala Book.

Adding dependencies

We now write a program that will count the files and directories present in its working directory. We use the os-lib library from the Scala toolkit for that purpose. A dependency on the library can be added with the //> using directive. Put the following code in counter.scala.

//> using scala 3.5.2
//> using dep "com.lihaoyi::os-lib:0.10.7"

@main
def countFiles(): Unit =
  val paths = os.list(os.pwd)
  println(paths.length)

In the code above, os.pwd returns the current working directory. We pass it to os.list, which returns a sequence of paths directly within the directory passed as an argument. We use a val to declare an immutable value, in this example storing the sequence of paths.

Execute the program. The dependency will be automatically downloaded. The execution should result in a similar output:

$ scala run counter.scala
Compiling project (Scala 3.5.2, JVM (20))
Compiled project (Scala 3.5.2, JVM (20))
4

The printed number should be 4: hello.scala, counter.scala and two hidden directories created automatically when a program is executed: .bsp containing information about project used by IDEs, and .scala-build containing the results of compilation.

As it turns out, the os-lib library is a part of Scala Toolkit, a collection of libraries recommended for tasks like testing, operating system interaction or handling JSONs. You can read more about the libraries included in the toolkit here. To include the toolkit libraries, use the //> using toolkit 0.5.0 directive:

//> using scala 3.5.2
//> using toolkit 0.5.0

@main
def countFiles(): Unit =
  val paths = os.list(os.pwd)
  println(paths.length)

This program is identical to the one above. However, other toolkit libraries will also be available to use, should you need them.

Using the REPL

You can execute code interactively using the REPL provided by the scala command. Execute scala in the console without any arguments.

$ scala
Welcome to Scala 3.5.2 (20-ea, Java OpenJDK 64-Bit Server VM).
Type in expressions for evaluation. Or try :help.

scala>

Write a line of code to be executed and press enter.

scala> println("Hello, World!")
Hello, World!

scala>

The result will be printed immediately after executing the line. You can declare values:

scala> val i = 1
val i: Int = 1

scala>

A new value of type Int has been created. If you provide an expression that can be evaluated, its result will be stored in an automatically created value.

scala> i + 3
val res0: Int = 4

scala>

You can exit the REPL with :exit.

Using an IDE

You can read a short summary of Scala IDEs on a dedicated page.

Let’s use an IDE to open the code we wrote above. The most popular ones are IntelliJ and VSCode. They both offer rich IDE features, but you can still use many other editors.

Prepare the project

First, remove all the using directives, and put them in a single file project.scala in the <project-dir> directory. This makes it easier to import as a project in an IDE:

//> using scala 3.5.2
//> using toolkit 0.5.0

Optionally, you can re-initialise the necessary IDE files from within the <project-dir> directory with the command scala setup-ide ., but these files will already exist if you have previously run the project with the Scala CLI run command.

Using IntelliJ

1. Download and install IntelliJ Community Edition
2. Install the Scala plugin by following the instructions on how to install IntelliJ plugins
3. Open the <project-dir> directory, which should be imported automatically as a BSP project.

Using VSCode with Metals

1. Download VSCode
2. Install the Metals extension from the Marketplace
3. Next, open the <project-dir> directory in VSCode. Metals should activate and begin importing the project automatically.

Play with the source code

View these three files in your IDE:

• project.scala
• hello.scala
• counter.scala

You should notice the benefits of an IDE, such as syntax highlighting, and smart code interactions. For example you can place the cursor over any part of the code, such as os.pwd in counter.scala and documentation for the method will appear.

When you run your project in the next step, the configuration in project.scala will be used to run the code in the other source files.

Run the code

If you’re comfortable using your IDE, you can run the code in counter.scala from your IDE. Attached to the countFiles method should be a prompt button. Click it to run the method. This should run without issue. The hello method in hello.scala needs arguments however, so will require extra configuration via the IDE to provide the argument.

Otherwise, you can run either application from the IDE’s built-in terminal as described in above sections.

Next steps

Now that you have tasted a little bit of Scala, you can further explore the language itself, consider checking out:

• The Scala Book (see the Scala 2 version here), which provides a set of short lessons introducing Scala’s main features.
• The Tour of Scala for bite-sized introductions to Scala’s features.
• Learning Resources, which includes online interactive tutorials and courses.
• Our list of some popular Scala books.

There are also other tutorials for other build-tools you can use with Scala:

• Getting Started with Scala and sbt
• Using Scala and Maven

Getting Help

There are a multitude of mailing lists and real-time chat rooms in case you want to quickly connect with other Scala users. Check out our community page for a list of these resources, and for where to reach out for help.