Buildpacks

Last updated 06 December 2016

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.

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.

You may also specify a buildpack during app creation:

$ heroku create myapp --buildpack heroku/python

Setting a buildpack in app.json

The buildpack can be explicitly set in app.json so that applications created via Heroku buttons can use custom buildpacks.

Buildpack modifications

You can change or remove a previously set buildpack again later:

$ heroku buildpacks:set heroku/nodejs
$ heroku buildpacks:remove heroku/nodejs

The 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

Detection failure

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.

-----> 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 custom Buildpack

You can use any unofficial or third-party buildpack by specifying a URL with the buildpacks:set command:

$ 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.

Buildpack references

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.

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.