Slug Compiler

Last updated December 03, 2024

Slugs are compressed and pre-packaged copies of your application optimized for distribution to the dyno manager. When you git push to Heroku, your code is received by the slug compiler which transforms your repository into a slug. Scaling an application then downloads and expands the slug to a dyno for execution.

This article is only applicable to apps that use classic buildpacks.

Compilation

The slug compiler is invoked by a git pre-receive hook, which follows these steps:

  1. Create a fresh checkout of HEAD from the master branch.
  2. Remove anything specified in a top-level .slugignore file.
  3. Download, build, and install local dependencies as specified in your build file (for example, Gemfile, package.json, requirements.txt, pom.xml, etc.) with the dependency management tool supported by the language (e.g. Bundler, npm, pip, Maven).
  4. Package the final slug archive.

Time limit

Slug compilation is currently limited to 15 minutes. If your deploys start timing out during compilation there are various strategies to speed things up, but these will vary based upon the build tool used. Very large applications which time out should usually have independent components spun off into separate libraries. Keep in mind that disk IO performance on dynos can vary widely, so in some cases compilations that finish in 10 minutes on a local SSD could take over 15 during deployment.

Ignoring files with .slugignore

If your repository contains files not necessary to run your app, you may wish to add these to a .slugignore file in the root of your repository. Examples of files you may wish to exclude from the slug:

  • Art sources (like .psd files)
  • Design documents (like .pdf files)
  • Test data

The format is roughly the same as .gitignore. Here’s an example .slugignore:

# Heres a comment
*.psd
*.pdf
/test
/spec

Heroku CI users: Do not list your test directory in .slugignore. It will be ignored and your test will not run under Heroku CI.

The .slugignore file causes files to be removed after you push code to Heroku and before the buildpack runs. This lets you prevent large files from being included in the final slug. Unlike .gitignore, .slugignore does not support negated ! patterns.

You can further reduce the number of unnecessary files (for example, log and tmp directories) by ensuring that they aren’t tracked by git, in which case they won’t be deployed to Heroku either. See Using a .gitignore file.

Slug size

Your slug size is displayed at the end of a successful compile after the Compressing message. The maximum allowed slug size (after compression) is 500 MB.

You can inspect the extracted contents of your slug with heroku run bash and by using commands such as ls and du.

Slug size varies greatly depending on what language and framework you are using, how many dependencies you have added and other factors specific to your app. Smaller slugs can be transferred to the dyno manager more quickly, allowing for more immediate scaling. You should try to keep your slugs as small and nimble as possible.

Here are some techniques for reducing slug size:

Build cache

Buildpacks can optionally cache content (such as app dependencies) to greatly speed up future builds.

If you suspect that a build problem is being caused by an error in this cache, you can use the heroku-builds plugin to purge/clear it:

$ heroku plugins:install @heroku-cli/heroku-builds
$ heroku builds:cache:purge

Feedback

Log in to submit feedback.