Last updated 26 May 2016
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.
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 Third-Party Buildpacks.
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.
It used to be possible to set a config var named
BUILDPACK_URL to declare which buildpack to use. If defined, its value will still be used, but a buildpack configured through
heroku buildpacks:set will take precedence, and the use of
BUILDPACK_URL is now deprecated.
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 can use custom buildpacks.
You can change or remove a previously set buildpack again later:
$ heroku buildpacks:set heroku/nodejs $ 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.
heroku buildpacks command provides a range of other capabilities around addition, modification and removal of buildpacks, some of which are particularly useful when employing multiple buildpacks. The
heroku help buildpacks command provides further details:
$ heroku help buildpacks Usage: heroku buildpacks Additional commands, type "heroku help COMMAND" for more details: buildpacks:add BUILDPACK_URL # add new app buildpack, inserting into list of buildpacks if neccessary buildpacks:clear # clear all buildpacks set on the app buildpacks:remove [BUILDPACK_URL] # remove a buildpack set on the app buildpacks:set BUILDPACK_URL # set new app buildpack, overwriting into list of buildpacks if neccessary
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.
The shorthand format does not support specifying branches, tags or versions of the buildpack with the
# notation. You must use a buildpack URL if you require anything other than the latest version of the official buildpack.
Using a custom Buildpack
You can use any unofficial or third-party buildpack by specifying a URL with the
$ heroku buildpacks:set https://github.com/heroku/heroku-buildpack-erlang Buildpack set. Next release on random-app-1234 will use https://github.com/heroku/heroku-buildpack-erlang. Run `git push heroku master` to create a new release using this buildpack.
You can also set the full URL of any official buildpack, which will cause the
master Git branch of that buildpack to be used instead of the last released version. As the latest Git version may contain unexpected changes, it is highly recommended to use the
heroku/… syntax for any of the official buildpacks.
Your buildpack value can point to either git repositories or a tarball URL. Hosting a buildpack on S3 can be a good way to ensure it’s highly available.
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 commit SHA, branch name or tag name) to the URL when invoking the
buildpacks:set command; for example:
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.