Last updated November 21, 2025

This document describes the general behavior of Heroku as it relates to the recognition and execution of Scala applications. For a more detailed explanation of how to deploy an application, 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. It’s intended to augment a command line in environments where the command line can’t be accessed or modified. If you must override these settings, you can either define your preferred options in the Procfile command, which takes precedence, or you can set your own JAVA_TOOL_OPTIONS config var.

Adjusting 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.4")

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 follow the recommendation to use sbt-native-packager to package your Scala application, the buildpack automatically creates the required process types to start your application. The buildpack detects the generated start script and creates a default web process type:

web: target/universal/stage/bin/appname

Play Framework applications also use sbt-native-packager, so they receive the same automatic process type configuration.

If you’re not using sbt-native-packager, you must 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