Last updated February 26, 2026

This guide walks you through deploying an existing Scala app to Heroku.

Prerequisites

Install Scala, sbt, and the Heroku CLI before proceeding. This guide assumes you have an existing Scala app that builds with sbt.

Overview

Heroku Scala Support describes how Heroku recognizes a Scala application.

Your application must include a project/build.properties file that defines the sbt version it uses:

sbt.version=1.10.7

For more information, see Build behavior.

Set Up the sbt-native-packager Plugin

To package your app for deployment, use the sbt-native-packager sbt plugin. If you’re using the Play framework, this plugin is automatically configured for you.

If you’re not using Play framework, configure the plugin manually. Add the following to your project/plugins.sbt file:

addSbtPlugin("com.github.sbt" % "sbt-native-packager" % "1.11.7")

Then enable the plugin in your build.sbt, for example JavaAppPackaging:

enablePlugins(JavaAppPackaging)

For more detailed information, see the sbt documentation and the sbt-native-packager documentation.

Specifying a Java Version

We recommend specifying a Java version for your app to ensure consistent builds. For more information, see Specifying a Java version.

The Procfile

A Procfile is a text file in the root directory of your application that defines process types and explicitly declares what command to run to start your app. If you use sbt-native-packager with the JavaAppPackaging archetype, you get a start script in target/universal/stage/bin. Your Procfile looks something like this, replacing hello with your app’s name:

web: target/universal/stage/bin/hello

This declares a single process type, web, and the command needed to run it. The name web attaches this process type to the HTTP routing stack of Heroku so it receives web traffic when deployed.

The command in a web process type must bind to the port number specified in the PORT environment variable. If it doesn’t, the dyno fails to start.

Exclude Build Artifacts from Git

Prevent build artifacts from going into revision control by creating a .gitignore file:

target/
project/boot

Customize the Build

By default, the buildpack runs compile stage as the sbt tasks during deployment. Customize this with the SBT_TASKS config var:

$ heroku config:set SBT_TASKS="compile stage dist" --app example-app

For multi-project sbt builds, set SBT_PROJECT to specify which project to build:

$ heroku config:set SBT_PROJECT=mySubProject --app example-app

Build and Run Locally

Build your app locally and start it:

$ sbt compile stage
$ heroku local --port 5001

Your app is now running on http://localhost:5001/.

Deploy to Heroku

Commit your changes to git and deploy your app:

$ git add .
$ git commit -m "Added a Procfile and packaging."
$ heroku login
...
$ heroku create
Creating app... done, stack is heroku-24
https://warm-frost-1289.herokuapp.com/ | https://git.heroku.com/warm-frost-1289.git
Git remote heroku added
$ git push heroku main
...
-----> Scala app detected

To open the app in your browser, run heroku open.

Console

Heroku allows you to run one-off dynos using the heroku run command. Use this to launch a REPL process attached to your local terminal for experimenting in your app’s environment:

$ heroku run sbt console
Running sbt console attached to terminal... up, run.1
...
scala>

For more information, see Running a Remote sbt Console for a Scala or Play Application.

Troubleshooting

Major releases of sbt may not be compatible with each other. Most issues will be related to mismatched versions of sbt.