Last updated February 26, 2026

This article describes how Heroku recognizes and executes Scala applications. For a step-by-step deployment guide, see Getting Started with Scala on Heroku.

Activation

Heroku recognizes Scala applications when sbt project files are found (such as *.sbt or project/build.properties).

When a deployed application is recognized as a Scala application, Heroku responds with -----> Scala app detected.

$ git push heroku main
...
-----> Scala app detected

You can deploy Scala applications that use Maven as well, but they’re treated as Java applications, so Heroku Java Support applies.

Environment Variables

The following environment variables are set in the dyno at boot-time:

• PORT: the web process binds to this HTTP port
• JAVA_HOME: the location of the JDK install directory
• LD_LIBRARY_PATH: the location of the JDK shared libraries
• JDBC_DATABASE_URL: If a DATABASE_URL variable is present, this variable is populated with the converted form. See Connecting to Relational Databases on Heroku with Java for more information.
• JAVA_TOOL_OPTIONS: default Java options based on dyno size

When a Java process is started on your dyno, the following Java options are automatically picked up:

• -Dfile.encoding=UTF-8

These options are configured as part of the environment variable JAVA_TOOL_OPTIONS, which augments the JVM command line automatically. To override these settings, define your preferred options in the Procfile command (which takes precedence) or set your own JAVA_TOOL_OPTIONS config var.

Adjust Environment for a Dyno Size

When you select a new dyno type some JVM flags are automatically added to JAVA_TOOL_OPTIONS.

Cedar

Cedar-generation dynos have JAVA_TOOL_OPTIONS set to the following per dyno size:

Fir

All Fir-generation dynos have JAVA_TOOL_OPTIONS set to -XX:MaxRAMPercentage=80.0.

Supported sbt versions

Applications must include a /project/build.properties file with the sbt.version property.

sbt release candidates, betas, and other pre-release versions of supported major versions are allowed.

Build Behavior

The Heroku Scala buildpack runs sbt compile stage to build the application. Applications must include a stage task, which performs any tasks needed to prepare an application to be run in-place.

sbt-native-packager

The recommended approach is to use sbt-native-packager, which adds a stage task to sbt that packages the application with all dependencies and generates start scripts. To use the plugin, create a /project/plugins.sbt file containing:

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

Then enable the plugin in your build.sbt:

enablePlugins(JavaAppPackaging)

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

Play Framework applications

Play Framework applications automatically include sbt-native-packager and don’t require any additional configuration. The Play plugin enables the necessary packaging and staging tasks out of the box.

Custom stage task

Or you can write a custom stage task by putting something like this in your build.sbt:

val stage = taskKey[Unit]("Stage task")

stage := {
  // Make stage depend on compile
  // You can depend on other tasks or add custom logic here
  (Compile / compile).value
}

You can test your task by running sbt compile stage locally.

Clean Builds

In some cases, builds must clean artifacts before compiling. If a clean build is necessary, configure builds to perform clean by setting SBT_CLEAN=true:

$ heroku config:set SBT_CLEAN=true
Setting config vars and restarting example-app... done, v17
SBT_CLEAN: true

All subsequent deploys use the clean task. To remove the clean task, unset SBT_CLEAN:

$ heroku config:unset SBT_CLEAN
Unsetting SBT_CLEAN and restarting example-app... done, v18

Runtime Behavior

If you use sbt-native-packager to package your Scala application, the buildpack automatically detects the generated start script and creates a default web process type:

web: target/universal/stage/bin/appname -Dhttp.port=$PORT

The -Dhttp.port=$PORT flag is included for Play Framework compatibility. Applications that don’t use this system property are not affected by it.

If you’re not using sbt-native-packager, provide a custom Procfile in the root of your project to specify how to start your application.

Supported JDK Versions

Refer to the Java support article.

Specifying a Java Version

Refer to the Java support article.

Postgres Auto-Provisioning

A Heroku Postgres database automatically provisions on the first deploy of your Scala applications. This auto-provisioning populates the DATABASE_URL environment variable.

If you don’t want the Postgres add-on, remove it by running:

$ heroku addons:destroy DATABASE --app example-app