IntelliJ IDEA 2024.1 Help


Working with sbt

When you've imported or created your sbt project, you can edit its build.sbt file directly in the editor. In build.sbt you can specify compiler options, information about your subprojects, and also define your tasks and settings. Every time you change the build.sbt file, you need to synchronize your changes with the project model in IntelliJ IDEA.

You can configure the Reload project after changes in the build scripts option to synchronize the changes made to build.sbt automatically. To access this option, select File | Settings | Build, Execution, Deployment | Build Tools.

For manual synchronization, use the corresponding action on the sbt projects tool window toolbar: Refresh.

Note that any sbt task can be attached to be run before a run configuration.

Open an existing sbt project

To create a new project, launch the New Project wizard and follow the steps suggested in the wizard such as selecting Scala and sbt; specifying the project's location, JDK along with sbt and Scala versions. (The sbt and Scala versions are fetched automatically).

If no project is currently opened in IntelliJ IDEA, click Open on the welcome screen (otherwise, select File | Open from the main menu). Then, in the dialog, select a file that contains your sbt project description build.sbt. Click OK, and - in the next dialog - click Select as Project.

IntelliJ IDEA opens and syncs the sbt project in the IDE. If you need to adjust importing options when you open the project, refer to the sbt settings.

Ensure sbt and Scala versions compatibility

Often you share your project across a team and need to use a specific version of sbt. You can override the sbt version in your project's file.

Create or open your sbt project. In the Project tool window, in the source root directory, locate the file and open it in the editor. Then, in the editor explicitly specify the version of sbt that you want to use in the project.


Reimport your project. (Click the in the sbt tool window.)

sbt project structure

When you create or import the sbt project, IntelliJ IDEA generates the following sbt structure:

  • sbt project (proper build) which defines a project and contains build.sbt file, src, and target directories, modules; anything related to a regular project.

    Project tool window
  • sbt build project which is defined in the project subdirectory. It contains additional code that is part of the build definition.

    sbt source root
  • the sbt tool window which contains sbt tasks, commands, and settings that you can execute.

    sbt tool window

Manage sbt projects

When you work with sbt projects you use the build.sbt file to make main changes to your project since IntelliJ IDEA considers the sbt configuration as a single source of truth.

Every time you manually change build.sbt in the editor, you need to load the changes. IntelliJ IDEA displays a notification icon in the right part of the editor suggesting to Load sbt Changes made to the project (Ctrl+Shift+O).

build.sbt file: Load sbt Changes

If you want to control the importing process of your project, you can manually trigger the action or configure the auto-reloading process.

Reload an sbt project

  1. In the sbt tool window, right-click a linked project.

  2. From the context menu, select Reload project the Reload project icon.

    On invoking this action, IntelliJ IDEA parses the project structure in the sbt tool window.

    IntelliJ IDEA cannot reload just a part of your project, it reloads the whole project including subprojects and dependencies.

Configure the auto-reload

  1. In the Settings dialog (Ctrl+Alt+S) , go to Build, Execution, Deployment | Build Tools.

    Alternatively, In the sbt tool window, click Build Tools Settings and select the Auto-Reload Settings option.

    the sbt tool window
  2. In the Build tools settings, specify the following options:

    the Build Tools settings
    • Reload changes in the build scripts: this option is selected by default. If you want to disable the auto-reload and manually control the reloading process, unselect this checkbox.

    • Any changes: select this option if you want to automatically reload the project after any changes you make to build.sbt or external changes.

      Every time you manually change the sbt build script in the editor, you need to load the changes. IntelliJ IDEA displays a notification icon in the right part of the editor suggesting to Load sbt Changes made to the project (Ctrl+Shift+O).

      sbt build script

      With the Any changes option, IntelliJ IDEA reloads all the changes automatically.

    • External changes: when you select this option, IntelliJ IDEA automatically reloads the project only after the VCS changes and changes made to the build files outside the IDE.

  1. Open your build.sbt.

  2. Specify the following code:

    val localDep = RootProject(file("/path/to/project"))

    localDep in this case is a project that is located somewhere on the file system and will be imported as a module.

  3. Reload your project. (Click the in the sbt tool window.)

    IntelliJ IDEA displays the added project in the Project tool window as well as in the sbt tool window.

Add a sub-project or a module to the sbt project

  1. Open build.sbt in the editor.

  2. Specify, for example:

    lazy val sampleModule = (project in file("sampleModule"))

    "sampleModule" in this case is a sub-project that you want to add. You can specify more than one sub-project.

  3. Reimport your project. (Click the Reimport project in the sbt tool window.)

    IntelliJ IDEA generates a subproject directory with the appropriate information and displays it in both Project and sbt tool windows.

Update subprojects

If you want the subprojects to automatically update when you change the version of Scala, specify commonSettings and settings method call for each subproject.

  1. Open build.sbt.

  2. Specify, for example, the following code:

    lazy val commonSettings = Seq( organization := "com.example", version := "0.1.0-SNAPSHOT", scalaVersion := "2.12.6" ) lazy val moduleSample = (project in file("moduleSample")) .settings( commonSettings )

    The appropriate Scala version is added to the sub-project's directory in the Project tool window and to the sbt tool window as a dependency in the sub-project.

Work with sbt shell

An sbt shell is embedded in the sbt project and is available on your project start. You can use the sbt shell for executing sbt commands and tasks, for running, and debugging your projects.

  • To start the sbt shell, press Ctrl+Shift+S (for Windows) or ⌘+⇧+S (for macOS). Alternatively, click sbt shell on the toolbar located at the bottom of the screen.

  • To use the sbt shell for build and import procedures, select the Use sbt shell section located in the sbt settings and perform steps described in the Run a Scala application using the sbt shell section.

  • To use the sbt shell for debugging, refer to the debugging with sbt shell section.

  • To run your tests from the sbt shell:

    1. Open a run/debug configuration (Run | Edit Configurations).

    2. Create a test configuration and select the use sbt option from the available settings.

Run sbt tasks

  • You can run sbt tasks by selecting the one you need from the sbt Tasks directory in the sbt tool window.

  • You can manually enter your task (code completion is supported) in the sbt shell and run it directly from there.

  • You can create a run configuration for a task. For example, you can create a custom task which is not part of the list of tasks located in the sbt tool window.

    1. Press Alt+Shift+F10 to open a run configuration.

    2. Specify the run configuration settings and click OK. If you need, you can add another configuration or a task to execute before running your configuration. Click the Add icon in the Before Launch section and from the list that opens, select what you need to execute.

  • When you work in the distraction-free mode (without toolbars and tool windows), you can run sbt tasks or commands from the Run Anything window. Press Ctrl twice to open it, type your command and press Enter.

IntelliJ IDEA displays results in the sbt shell window.

Work with sbt settings

Use the sbt settings to configure the build and run actions the sbt project, an sbt version, importing of the project's changes, and so on.

Access the sbt settings

  1. Press Ctrl+Alt+S to open settings and then select Build, Execution, Deployment| sbt.

  2. Alternatively, click sbt Settings on the toolbar of the sbt tool window to access the sbt settings.

  3. On the sbt settings page, configure the following notable actions:

    • To delegate running builds to sbt, next to Use sbt shell, select the for imports and for builds options.

    • To debug your code via the sbt shell, select Enable debugging for sbt shell option that enables the debug button in the sbt shell tool window.

      For more information about debugging, refer to debugging with sbt.

    • To change the .ivy cache location in your project or set other sbt properties, use the VM parameters field.

  4. Click OK to save the changes.

To check the most common sbt issues and workarounds, refer to the sbt troubleshooting section.

Last modified: 26 May 2024