Skip to content
Tutorials Center
My learning

Topics

Lesson 8 of 37 ยท Apps, Dynos and Buildpacks

Buildpacks

Learn how Heroku buildpacks turn source code into a slug: the detect, compile and release steps, setting and ordering multiple buildpacks, and writing custom ones.

A buildpack is a set of scripts that knows how to prepare one kind of application to run. The Node.js buildpack installs Node and your npm packages; the Python buildpack installs Python and runs pip; the Ruby buildpack runs Bundler and can precompile Rails assets. When you push code, Heroku runs the right buildpack and the result is the slug your dynos run.

You rarely need to think about buildpacks on a simple app because Heroku detects the right one by itself. The moment you add a front-end build to a Python app, or need a system tool the stock image lacks, buildpacks become the thing to understand.

The three steps of a classic buildpack

A buildpack is, at its core, three executables in a bin/ folder:

  1. bin/detect gets the path of your code and answers "can I handle this?" It prints a name and exits 0 for yes, non-zero for no. The Node.js buildpack says yes if a package.json exists.
  2. bin/compile does the work: install the runtime, install dependencies, run build commands, and leave everything the app needs in the build directory. It also has a cache directory that persists between builds, which is why a second deploy is faster than the first.
  3. bin/release (optional) prints default config and default process types as YAML, such as a default web command. A Procfile overrides defaults.
flowchart LR
  S["Your source"] --> D{"bin/detect"}
  D -->|"yes"| C["bin/compile<br/>runtime + dependencies"]
  C --> R["bin/release<br/>defaults"]
  R --> SL["Slug"]

A buildpack answers yes or no, builds the app, and may supply default process types.

Heroku maintains official buildpacks for the main languages (Node.js, Ruby, Python, Java, PHP, Go, Scala, Clojure and others), plus community buildpacks you can use by Git URL. The newer Cloud Native Buildpacks standard is also supported by the platform's newer generation, with its own detect and build phases; the ideas in this lesson carry over.

Seeing and setting buildpacks

CONSOLE
$ heroku buildpacks
$ heroku buildpacks:set heroku/python
$ heroku buildpacks:add --index 1 heroku/nodejs
$ heroku buildpacks:remove heroku/nodejs
$ heroku buildpacks:clear
  • Without any set, Heroku auto-detects on each deploy.
  • buildpacks:set locks the app to one buildpack and stops auto-detection. A new release is not created by this command; the buildpack applies to the next build.
  • buildpacks:add adds another buildpack to the list; --index chooses the position.
  • A community buildpack is added by URL: heroku buildpacks:add https://github.com/owner/buildpack-name. Remember that a buildpack runs arbitrary code during your build, so only use ones you trust and pin them to a tag or commit when you can.

Multiple buildpacks

Real apps often mix languages. A Django app with a React front end needs Node.js to build the JavaScript and Python to run the server. Heroku runs the buildpacks in order, each seeing the output of the previous:

CONSOLE
$ heroku buildpacks:add --index 1 heroku/nodejs
$ heroku buildpacks:add --index 2 heroku/python
$ heroku buildpacks
=== demo-shop Buildpack URLs
1. heroku/nodejs
2. heroku/python

Two rules shape how you order them:

  • The last buildpack decides the default process type (what runs if no Procfile exists), so put the language that actually serves requests last.
  • Each buildpack in the list must be able to run (its detect passes) unless you set them explicitly, in which case Heroku trusts you.

A typical use is putting a tool buildpack first: for instance, one that installs a system package your build needs, followed by the language buildpack. The build cache is kept per buildpack.

Stand-in: run a list of buildpacks

This stand-in models the order of execution and the rule that the last buildpack provides the default web command. The buildpack names and behavior are made up for practice; they are not real buildpack output.

Python Stand-in: ordered buildpacks and the default process

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Swap the list order in the program and watch the default web command change. That is the whole "last buildpack wins" rule.

Stand-in: a classic buildpack contract

To see how simple the contract is, here is a pure Python rendition of the three scripts. It prints what a real buildpack would do in plain words, and never touches a file system.

Python Stand-in: detect, compile, release

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Deploy 2 is fast because the dependency list did not change. That is the cache working.

Practical advice

  • Pin the language version in your project files rather than relying on defaults. See stacks and runtime versions.
  • Keep builds small. Slugs have a size limit (500 MB compressed), and large slugs slow dyno start-up. Remove dev-only dependencies where the buildpack supports it.
  • Clear the build cache when a stale dependency breaks a build: the Dev Center documents the heroku-builds plugin (heroku builds:cache:purge).
  • Prefer official buildpacks. Reach for a third-party one only when you need something official ones do not offer.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What is the job of a buildpack's detect step?

    detect inspects the source and exits successfully only if the buildpack can handle it.
  2. 2. With several buildpacks, which one provides the default process types?

    The last buildpack in the list decides the default process type, so it should be the one that serves requests.
  3. 3. Why is a second deploy often faster than the first?

    Buildpacks keep a cache between builds, so unchanged dependencies are not downloaded again.
  4. 4. Which command locks an app to a single buildpack?

    buildpacks:set replaces the list with one entry and stops auto-detection.
  5. 5. What is a good reason to be careful with community buildpacks?

    A buildpack runs arbitrary code during the build, so use trusted sources and pin versions.

Summary

  • A buildpack detects, compiles and optionally provides release defaults for one kind of app.
  • Heroku auto-detects by default; heroku buildpacks:set/add controls the list explicitly.
  • Multiple buildpacks run in order, and the last one decides default process types.
  • Pin runtime versions, keep slugs small and treat third-party buildpacks as code you are trusting.

Next: Stacks and runtime versions