Last updated March 09, 2022
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.
The slug compiler is invoked by a git pre-receive hook, which follows these steps:
- Create a fresh checkout of HEAD from the master branch.
- Remove anything specified in a top-level
- Download, build, and install local dependencies as specified in
your build file (for example, Gemfile,
pom.xml, etc.) with the dependency management tool supported by the language (e.g. Bundler, npm, pip, Maven).
- Package the final slug archive.
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
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
# Heres a comment
Heroku CI users: Do not list your test directory in
.slugignore. It will be ignored and your test will not run under Heroku CI.
.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
.slugignore does not support negated
You can further reduce the number of unnecessary files (for example,
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.
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
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:
- Move large assets like PDFs or audio files to asset storage.
- Remove unneeded dependencies and exclude unnecessary files via
- Purge the 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-builds
$ heroku builds:cache:purge