Buildpacks

Last updated 12 September 2017

Table of Contents

• Officially supported buildpacks
• Setting a buildpack on an application
• Using multiple buildpacks
• Creating a buildpack

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 theslug 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 pushesto your application as if you had runheroku buildpacks:setmanually asexplained 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, seeThird-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 aconfig varnamedBUILDPACK_URLto declare which buildpack to use. If defined, its value will still be used, but a buildpack configured throughheroku buildpacks:setwill take precedence, and the use ofBUILDPACK_URLis now deprecated.

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 inapp.jsonso 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
odejs
$ 
heroku buildpacks:remove heroku
odejs

When no buildpack is set on your application, thedetection processwill be run again on your nextgit push heroku.

Theheroku buildpackscommand provides a range of other capabilities around addition, modification and removal of buildpacks, some of which are particularly useful when employingmultiple buildpacks. Theheroku help buildpackscommand 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 itsdetection script), you will receive an error. For example, Heroku’s Ruby buildpack expects aGemfileto be present in the root folder of an application to correctly identify its type, but if the buildpack of an application is set toheroku/rubyand noGemfileis 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 acomposer.jsoncontained apackage.jsonwith NPM packages for asset handling, the application would have been detected as a Node.js application on first push due to theorder in which default buildpacks are invoked for detection.

The removal ofpackage.jsonin this case would not automatically reconfigure the buildpack used for the application - the buildpack is “pinned” toheroku/nodejs, and attempting agit pushwithout apackage.jsonwould result in an error:

-----
>
 Using set buildpack heroku/nodejs
 !     Push rejected, failed to detect set buildpack heroku/nodejs

You would now need to manuallyclear the buildpackorset the desired buildpack- in this example, toheroku/php.

Using an official buildpack

If Heroku’s auto-detection of buildpacks is not sufficient, or if you needmultiple buildpacksyou 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 ofheroku/ruby, you may use any of the other shorthand identifiers listed above in thetable 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 thebuildpacks:setcommand:

$ 
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 themasterGit 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 theheroku/…syntax for any of the official buildpacks.

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.

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 Gitobject(e.g. a commit SHA, branch name or tag name) to the URL when invoking thebuildpacks:setcommand; for example:

• https://github.com/heroku/heroku-buildpack-nodejs.git#somedevbranch
• https://github.com/heroku/heroku-buildpack-ruby.git#v9861

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 usingPgBouncer, 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 toUsing 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 .