What is the Aptfile

The Aptfile is a file to keep a list of packages you want apt to install for you when running a particular buildpack on Heroku. Let’s dig into what that means!

I believe the hosting company Heroku created Aptfiles. I’ve certainly never heard of them in any other context.

Heroku creates a Linux environment for your code to run on. An out-of-the-box Linux install has lots of stuff, but not everything needed to run a web project.

You can layer on other stuff using what Heroku calls buildpacks; these are scripts that run after it installs Linux which can install some extra stuff for you. For example, the Ruby buildpack will install bundler and things needed to get a Ruby project up and running.

For not-so-common things, there are community buildpacks, which generally install specific packages needed to perform a particular purpose. Heroku doesn’t maintain these directly, but many still receive regular support and care.

Sometimes though, you only need to install one extra thing, or maybe you need to install so many things that you would have loads of different buildpacks, which would become unwieldy.

Enter the Aptfile!

Linux has a package manager called apt. You can use it to install packages. apt get my-package would install my-package for you.

The Aptfile is a text file where each line is the package you want to install.

An Aptfile like so;

my-package
your-package

Is the equivalent of running;

apt get my-package
apt get your-package

apt will install the package mentioned and any of its dependencies.

To make use of the Aptfile, you need to use the heroku-buildpack-apt buildpack.

Three ways to get packages

The Aptfile gives you three ways to define which packages you want to install;

• package name, as we saw above: my-package
• linking to a specific .deb package: https://download.package.com/my-package.deb
• by using custom apt repositories: :repo:deb https://apt.example.com/ example-distro main

Advantages to the Aptfile

The main advantages of the Aptfile over individual buildpacks are;

• less overhead if you only need one package
• the Aptfile is committed to code, making it easier for developers to change

We recommend using the Aptfile over community buildpacks when you have a simple use case, and the Aptfile is easy to manage.

Disadvantages to the Aptfile

The main disadvantages to using Aptfile over individual buildpacks are;

• won’t get improvements to the overall build from the community over time
• if a package changes, your build might break with little support
• need to document why specific packages are required; when bundled into a buildpack, this is generally self-documenting

If the Aptfile needs to install lots of things that are all needed for one feature, if that feature has a buildpack, then we would suggest using it. It gives you one less thing to have to worry about.

How do I create an Aptfile?

Open or create a file called Aptfile (note, there is no file extension like .txt after it) in your text editor of choice and write down your packages or Debian links one on each line.

Ordering Aptfile buildpack

Heroku lets you adjust the order of your buildpacks, and the order is important. We suggest always having your heroku-buildpack-apt buildpack come first, followed by any custom buildpacks, then your “main” buildpack.

Having your Aptfile run first means anything you install will be available to later buildpacks.