Slug Compiler

Last updated March 06, 2026

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 limited to 25 minutes. If your deploys start timing out during compilation, there are various strategies to speed up deployment. These strategies vary based on the build tool you use. Very large applications that time out usually have independent components spun off into separate libraries. Keep in mind that disk IO performance on dynos can vary widely, so sometimes compilations that finish in 10 minutes on a local SSD can take over 25 minutes 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 default maximum-allowed slug size after compression is 1000 MB. Open a support ticket if you must raise this limit.

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. Try to keep your slugs as small as possible, since smaller slugs can be transferred to the dyno manager more quickly, allowing for dynos to start more quickly.

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