Last updated August 21, 2023
Table of Contents
Buildpacks are responsible for transforming deployed code into a slug, which can then be executed on a dyno. Buildpacks are composed of a set of scripts, and depending on the programming language, the scripts will retrieve dependencies, output generated assets or compiled code, and more. This output is assembled into a slug by the slug compiler.
Heroku’s support for Ruby, Python, Java, Clojure, Node.js, Scala, Go and PHP is implemented via a set of open source buildpacks.
Officially supported buildpacks
Heroku maintains a collection of officially supported buildpacks that are available by default to all Heroku apps during slug compilation.
These buildpacks are open-source and available on GitHub. If you have a change that would be useful to all Heroku developers, we encourage you to submit a pull request.
|Grails 3.x||heroku/gradle||Documentation||Runtime versions|
|Play 2.x||heroku/scala||Documentation||Runtime versions|
By default, these buildpacks will be searched in this order until a match is detected and used to compile your app. If the build succeeds, the detected buildpack will be permanently set for future pushes to your application as if you had run
heroku buildpacks:set manually as explained below.
Custom buildpacks can be used to support languages or frameworks that are not covered by Heroku’s officially supported buildpacks. For a list of known third-party buildpacks, see Using a third-party buildpack.
Setting a buildpack on an application
You can change the buildpack used by an application by setting the buildpack value. When the application is next pushed, the new buildpack will be used.
$ heroku buildpacks:set heroku/php Buildpack set. Next release on random-app-1234 will use heroku/php. Run `git push heroku master` to create a new release using this buildpack.
You may also specify a buildpack during app creation:
$ heroku create myapp --buildpack heroku/python
Setting a buildpack in
The buildpack can be explicitly set in
app.json so that applications created via Heroku buttons, Heroku CI or Review Apps can use custom buildpacks. Changing
app.json won’t update the settings of existing apps, you will need to use the
heroku buildpacks command instead.
Removing a buildpack from an app
You can easily remove a buildpack from an app:
$ heroku buildpacks:remove heroku/nodejs
When no buildpack is set on your application, the detection process will be run again on your next
git push heroku.
If the configured buildpack cannot handle your application (as determined by its detection script), you will receive an error. For example, Heroku’s Ruby buildpack expects a
Gemfile to be present in the root folder of an application to correctly identify its type, but if the buildpack of an application is set to
heroku/ruby and no
Gemfile is present, the application will fail to build.
This situation may also occur if you remove or rename a file that previously led to the automatic detection of your application type and thus the automatic setting of the detected buildpack on your application.
For example, had you pushed an application written in PHP, which in addition to a
composer.json contained a
package.json with NPM packages for asset handling, the application would have been detected as a Node.js application on first push due to the order in which default buildpacks are invoked for detection.
The removal of
package.json in this case would not automatically reconfigure the buildpack used for the application - the buildpack is “pinned” to
heroku/nodejs, and attempting a
git push without a
package.json would result in an error:
-----> Using set buildpack heroku/nodejs ! Push rejected, failed to detect set buildpack heroku/nodejs
Using an official buildpack
If Heroku’s auto-detection of buildpacks is not sufficient, or if you need multiple buildpacks you can configure your app to run with one of the default buildpacks by executing a command such as this:
$ heroku buildpacks:set heroku/ruby Buildpack set. Next release on random-app-1234 will use heroku/ruby. Run `git push heroku master` to create a new release using this buildpack.
This example forces Heroku to use the latest release version of the official Ruby buildpack on your next deployment (and every deployment after unless you change it). Instead of
heroku/ruby, you may use any of the other shorthand identifiers listed above in the table of official buildpacks.
Using a third-party buildpack
If Heroku’s official buildpacks don’t support your app’s requirements, check out the curated list of custom, third-party buildpacks in the Elements marketplace. You can also search through hundreds of custom buildpacks via the CLI. To search, run:
$ heroku buildpacks:search elixir Buildpack Category Description ─────────────── ───────── ─────────────────────────── hashnuke/elixir languages Heroku Buildpack for Elixir $ heroku buildpacks:info hashnuke/elixir description: Heroku Buildpack for Elixir category: languages license: MIT License support: https://github.com/HashNuke/heroku-buildpack-elixir/issues source: https://github.com/HashNuke/heroku-buildpack-elixir readme: $ heroku buildpacks:set hashnuke/elixir Buildpack set. Next release on agile-plains-12843 will use hashnuke/elixir. Run git push heroku master to create a new release using this buildpack.
Third-party buildpacks contain software that is not under Heroku’s control, and they are not officially supported by Heroku. Please inspect the source of any buildpack you plan to use and proceed with caution.
You can specify the buildpack namespace/name or Git URL of a third-party buildpack when creating a new app:
$ heroku create myapp --buildpack https://github.com/some/buildpack.git
You can also do so for an existing app like so:
$ heroku buildpacks:set https://github.com/some/buildpack.git -a myapp
You can return to using your app’s default Heroku buildpack with the following command:
$ heroku buildpacks:clear
Buildpack values can be set to any of:
- the short-form Buildpack Registry name (for published buildpacks), eg:
- the URL of a Git repository, eg
- a gzipped tarball URL
Heroku will not provide support for official buildpacks unless the latest stable release is used via the
heroku/… shorthand name.
Using an official buildpack’s GitHub URL may result in degraded performance or undocumented behavior.
When the source of the buildpack you wish to use is a Git repository, you can specify a specific tag or branch of that buildpack to be used by appending a Git object (e.g. a tag name, branch name or 40 character commit SHA) to the URL. For example:
Never set a branch name or commit reference using the
….git#ref notation unless explicitly instructed to do so by Heroku Support as a temporary measure,
as this may result in your application not utilizing up-to-date and secure dependencies, builds failing, or undefined behavior at runtime.
Using multiple buildpacks
There are many scenarios in which a single buildpack is not sufficient when building an application. Typical scenarios include database connection pooling using PgBouncer, or asset handling using a Node.js library in combination with a Ruby, Python or PHP application.
When this is the case, please follow our guide to Using Multiple Buildpacks for an App.
Creating a buildpack
If you’d like to use a language or framework not yet supported on Heroku you can create a custom buildpack. To get started, see the following articles:
- To learn about the structure of a buildpack, see Buildpack API.
If you would like to create a build manifest, which can be checked into source control and allows you to easily install packages, learn more about heroku.yml