Quick Start Guide

This guide will walk you through creating your first sbt project and introduce you to the essential commands and concepts.

Make sure you have installed sbt before continuing.

Create Your First Project

Let’s create a simple “Hello World” Scala application.

Create a project directory

mkdir hello-world
cd hello-world

Create the build definition

Create a file named build.sbt in the project root:

build.sbt

name := "hello-world"
version := "0.1.0"
scalaVersion := "3.8.2"

This minimal build file tells sbt:

Your project’s name is “hello-world”
The version is “0.1.0”
You’re using Scala 3.8.2

The := operator sets a value for a setting. Think of it as assignment for build configuration.

Create your source file

Create the source directory structure and your first Scala file:

mkdir -p src/main/scala

Create src/main/scala/Main.scala:

src/main/scala/Main.scala

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

This uses Scala 3’s @main annotation to create an entry point.

Start the sbt shell

Launch sbt’s interactive shell:

sbt

The first time you run sbt, it will:

Download the sbt launcher and dependencies (this may take a minute)
Load your project
Present you with the sbt prompt: sbt:hello-world>

The sbt shell keeps your project loaded in memory, making subsequent commands much faster than running sbt separately each time.

Compile your project

At the sbt prompt, compile your code:

compile

You’ll see output like:

[info] compiling 1 Scala source to /path/to/hello-world/target/scala-3.8.2/classes ...
[success] Total time: 2 s

Your compiled classes are now in target/scala-3.8.2/classes/.

Run your application

Execute your program:

run

You should see:

[info] running hello
Hello, World!
Welcome to sbt!
[success] Total time: 0 s

Congratulations! You’ve built and run your first sbt project!

Understanding the Project Structure

Your project now looks like this:

hello-world/
├── build.sbt                    # Build definition
├── project/
│   ├── build.properties         # sbt version (auto-generated)
│   └── target/                  # Build metadata
├── src/
│   ├── main/
│   │   ├── scala/              # Your Scala source files
│   │   │   └── Main.scala
│   │   ├── java/               # Java sources go here (if any)
│   │   └── resources/          # Non-code files (configs, etc.)
│   └── test/
│       ├── scala/              # Test source files
│       └── resources/          # Test resources
└── target/                      # Compiled output and generated files

The target/ directory contains all generated files and can be safely deleted. sbt will regenerate it when needed.

Essential sbt Commands

Here are the most common commands you’ll use in the sbt shell:

compile          # Compile main sources
Test / compile   # Compile test sources

You can run these commands from the sbt shell (recommended) or as one-off commands like sbt compile from your terminal.

Continuous Build

One of sbt’s most powerful features is watching for file changes:

~compile    # Recompile when sources change
~test       # Re-run tests when sources change  
~run        # Re-run your app when sources change

The ~ prefix tells sbt to watch for changes and automatically re-execute the command. Press Enter to stop watching.

Use ~testQuick during development to automatically run only the tests affected by your changes. It’s a huge productivity boost!

Adding Dependencies

Let’s add a library dependency to your project. Update your build.sbt:

build.sbt

name := "hello-world"
version := "0.1.0"
scalaVersion := "3.8.2"

libraryDependencies += "org.typelevel" %% "cats-core" % "2.10.0"

The %% operator automatically adds the Scala version suffix (e.g., cats-core_3). After saving, reload sbt:

reload

sbt will download the dependency and its transitive dependencies.

Adding Test Dependencies

To add a testing library like ScalaTest:

build.sbt

libraryDependencies += "org.scalatest" %% "scalatest" % "3.2.19" % Test

The % Test scope means this dependency is only available for test code.

Working with Tests

Let’s add a test to your project.

Add ScalaTest dependency

Update build.sbt:

build.sbt

name := "hello-world"
version := "0.1.0"
scalaVersion := "3.8.2"

libraryDependencies += "org.scalatest" %% "scalatest" % "3.2.19" % Test

In the sbt shell, reload:

reload

Create a test file

Create src/test/scala/HelloSpec.scala:

src/test/scala/HelloSpec.scala

import org.scalatest.flatspec.AnyFlatSpec
import org.scalatest.matchers.should.Matchers

class HelloSpec extends AnyFlatSpec with Matchers {
  "A greeting" should "contain Hello" in {
    val greeting = "Hello, World!"
    greeting should include ("Hello")
  }

  it should "be friendly" in {
    val greeting = "Hello, World!"
    greeting should endWith ("World!")
  }
}

Run the tests

test

You should see:

[info] HelloSpec:
[info] A greeting
[info] - should contain Hello
[info] - should be friendly
[info] Run completed in 321 milliseconds.
[info] Total number of tests run: 2
[info] Suites: completed 1, aborted 0
[info] Tests: succeeded 2, failed 0, canceled 0, ignored 0, pending 0
[info] All tests passed.
[success] Total time: 1 s

Interactive Shell Features

The sbt shell has several productivity features:

Tab Completion

Press Tab to see available commands or complete partial commands:

sbt:hello-world> com[Tab]
compile     console     consoleQuick

Command History

Use Up/Down arrows to navigate command history, just like in your shell.

Multi-Command Execution

Run multiple commands separated by semicolons:

clean ; compile ; test

Command Aliases

Define shortcuts in your build.sbt:

build.sbt

addCommandAlias("testc", ";clean;test")
addCommandAlias("cq", "~testQuick")

Now you can run testc instead of typing clean ; test.

Specifying the sbt Version

Create project/build.properties to specify which sbt version your project uses:

project/build.properties

sbt.version=2.0.0-RC9

This ensures everyone working on the project uses the same sbt version, and the sbt launcher will automatically download it if needed.

Next Steps: Java Example

Sbt works great with Java too! Here’s a quick Java example:

Create a Java project

mkdir hello-java
cd hello-java

Create build.sbt:

build.sbt

name := "hello-java"
version := "0.1.0"

// No Scala version needed for pure Java projects
crossPaths := false
autoScalaLibrary := false

Create Java source

Create src/main/java/Hello.java:

src/main/java/Hello.java

public class Hello {
    public static void main(String[] args) {
        System.out.println("Hello from Java!");
    }
}

Build and run

sbt compile run

Output:

[info] compiling 1 Java source to target/classes ...
[info] running Hello
Hello from Java!
[success] Total time: 1 s

Common Patterns

Setting Java Version

To specify Java compiler version:

build.sbt

javacOptions ++= Seq("-source", "17", "-target", "17")

Running with Arguments

Pass arguments to your application:

run arg1 arg2 arg3

Forking the JVM

Run your application in a separate JVM:

build.sbt

fork := true

Setting JVM Options

build.sbt

javaOptions ++= Seq("-Xmx512m", "-Dconfig.file=conf/application.conf")

Troubleshooting

Compilation Errors

If you see compilation errors:

Check that your Scala version matches your code (Scala 2 vs Scala 3 syntax differs)
Make sure source files are in the correct directory (src/main/scala/)
Verify dependencies are correctly specified in build.sbt

Dependency Resolution Issues

If dependencies fail to download:

# Clear the cache and retry
clean
update

Out of Memory

If you get OutOfMemory errors:

# Exit sbt and set memory options
export SBT_OPTS="-Xmx2G"
sbt

Reload After Changes

Always reload after editing build.sbt:

reload

Learning More

Now that you’ve created your first project, dive deeper:

Build Definition

Learn about settings, tasks, scopes, and how to structure complex builds

Dependency Management

Master library dependencies, resolvers, and managing transitive dependencies

Multi-Project Builds

Organize large codebases with multiple subprojects and shared settings

Plugins

Extend sbt with plugins for testing, packaging, deployment and more

Quick Reference

sbt              # Start interactive shell
sbt compile      # One-off compile
sbt "run arg1"   # Run with arguments (note quotes)
sbt clean test   # Clean then test

Keep the sbt shell running during development. Starting it once and reusing it is much faster than restarting sbt for every command.

Summary

You’ve learned:

✅ How to create a new sbt project from scratch
✅ The standard project structure (src/main/scala, build.sbt)
✅ Essential commands: compile, run, test, reload
✅ How to add dependencies to your project
✅ Continuous build with the ~ prefix
✅ Working with the interactive shell
✅ Both Scala and Java project setup

Happy building with sbt!

Documentation Index

​Quick Start Guide

​Create Your First Project

​Understanding the Project Structure

​Essential sbt Commands

​Continuous Build

​Adding Dependencies

​Adding Test Dependencies

​Working with Tests

​Interactive Shell Features

​Tab Completion

​Command History

​Multi-Command Execution

​Command Aliases

​Specifying the sbt Version

​Next Steps: Java Example

​Common Patterns

​Setting Java Version

​Running with Arguments

​Forking the JVM

​Setting JVM Options

​Troubleshooting

​Compilation Errors

​Dependency Resolution Issues

​Out of Memory

​Reload After Changes

​Learning More

Build Definition

Dependency Management

Multi-Project Builds

Plugins

​Quick Reference

​Summary

Quick Start Guide

Create Your First Project

Understanding the Project Structure

Essential sbt Commands

Continuous Build

Adding Dependencies

Adding Test Dependencies

Working with Tests

Interactive Shell Features

Tab Completion

Command History

Multi-Command Execution

Command Aliases

Specifying the sbt Version

Next Steps: Java Example

Common Patterns

Setting Java Version

Running with Arguments

Forking the JVM

Setting JVM Options

Troubleshooting

Compilation Errors

Dependency Resolution Issues

Out of Memory

Reload After Changes

Learning More

Quick Reference

Summary