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. Download, build, and install local dependencies as specified in your build file (e.g. Gemfile, package.json, requirements.txt, etc.)
3. Remove unused files, including the .git directory, anything in log and tmp, local build dependencies such as .gem files in the bundled gems directory, and anything specified in a top-level .slugignore file.
4. Write the environment into the slug. (The slug is rebuilt any time a config var or add-on is changed)
5. 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. Here’s an example .slugignore:

*.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.

$ du -hsc | grep total
2.9M total

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

Smaller slugs can be transferred across the dyno grid more quickly allowing for more immediate scaling. Generally speaking any slug under 15MB is small and nimble; 30MB is average; and 50MB or above is weighty. If you find your app getting into the 50MB+ range, you may want to look into some techniques (such as removing unneeded dependencies or excluding files via .slugignore) to reduce the size.