slug compiler

Slugs are compressed and pre-packaged copies of your application optimized for lightning-fast distribution across the dyno manifold. 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.

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 unused files, including the .git directory, anything in log and tmp, and 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.

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:

• Unit tests or specs
• Art sources (like .psd files)
• Design documents (like .pdf files)
• Test data

The format is roughly similar to .gitignore, except it does not support the negation operator !. Here's an example .slugignore:

:::text
*.psd
*.pdf
test
spec

The .slugignore file ensures that matching assets, that were pushed to Heroku when you deployed your application, are not included in the final slug.

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. You can roughly estimate slug size locally by doing a fresh checkout of your app, deleting the .git directory, and running du -hsc.

:::term
$ du -hsc | grep total
2.9M total

The maximum slug size is 200MB. Most apps should be far below this size.

Smaller slugs can be transferred across the dyno manifold more quickly allowing for more immediate scaling. Generally speaking any slug under 15MB is small and nimble; 50MB is average; and 90MB or above is weighty.

If you find your app getting into the 90MB+ range, you may want to look into some techniques for reducing its size:

• Move large assets like PDFs or audio files to asset storage.
• Remove unneeded dependencies and exclude unnecessary files via .slugignore.
• For Ruby, when possible reference a released gem by name in your Gemfile rather than loading it from source using the :git option.