Introduction

A Heroku slug is the packaged build output that Heroku runs after deployment. When you hit a "slug size too large" error for a Python app, the real problem is almost always that your repository or dependency set contains files that do not belong in the runtime artifact, such as caches, test data, large models, compiled assets, or oversized libraries.

Understand What Ends Up in the Slug

The slug is not just your Python source files. It can include:

• installed dependencies from requirements.txt
• application code
• static assets committed into the repository
• files not excluded from the build context

That is why the first debugging question is not "how big is my app code" but "what exactly is Heroku packaging and installing."

Remove Files That Do Not Belong in Production

Heroku supports a .slugignore file that works similarly to .gitignore, but specifically for slug contents.

A typical example might look like this:

1tests/
2docs/
3notebooks/
4*.mp4
5*.zip
6data/

If your repository contains local experiment data, notebooks, screenshots, or trained model artifacts that are not needed at runtime, exclude them.

This is often the fastest win because large files contribute to slug size immediately.

Audit Python Dependencies Aggressively

Heavy packages are another common cause. Check whether every dependency in requirements.txt is truly needed in production.

For example, if your runtime does not need Jupyter, local test tooling, or extra scientific packages, do not ship them.

A lean deployment list should focus on runtime dependencies only:

Flask==3.0.0
gunicorn==21.2.0
psycopg2-binary==2.9.9

Instead of mixing in development-only packages:

1pytest
2black
3jupyter
4matplotlib

Those tools are useful locally, but they often do not belong in the Heroku slug.

Move Large Data and Models Out of the Slug

If the application uses large machine learning models, media assets, or generated datasets, Heroku is usually the wrong place to store them inside the slug. Put them in object storage or another external service and fetch them when needed.

Common alternatives include:

• Amazon S3
• cloud database storage
• external CDN or asset host
• model registry or artifact store

This keeps the deployment artifact small and makes updates to large assets independent from application releases.

Inspect the Repository for Accidental Bloat

It is easy to commit files that look harmless but inflate the slug drastically. Typical examples are:

• local virtual environments
• '.pytest_cache'
• '__pycache__'
• generated front-end bundles
• build directories
• sample data snapshots

Make sure these are excluded from Git and, when appropriate, from the slug.

A quick local check helps:

du -sh .
du -sh * | sort -h

This does not tell you the exact slug size, but it quickly reveals the biggest directories in the project.

Build for Runtime, Not for Development Convenience

Heroku runtime environments reward minimalism. If your app requires large native libraries, giant datasets, or unusual system tooling, that is often a signal to rethink the platform fit or use a container-based deployment path instead.

That does not mean Heroku cannot run Python apps well. It means the app needs to be packaged intentionally, with a clean separation between source code, runtime dependencies, and non-runtime assets.

Common Pitfalls

• Keeping notebooks, datasets, or media files in the deployed repository bloats the slug immediately.
• Shipping development-only Python packages in requirements.txt increases build size for no production benefit.
• Assuming .gitignore alone controls slug contents is risky. Use .slugignore for Heroku-specific exclusions.
• Bundling large models or static assets into the app instead of external storage makes the slug hard to manage and redeploy.
• Treating the slug limit as a one-time deployment problem misses the deeper issue, which is usually unclear runtime packaging boundaries.

Summary

• Heroku slug size errors usually come from oversized files or unnecessary dependencies, not from normal Python source code.
• Use .slugignore to exclude non-runtime files from the slug.
• Keep requirements.txt limited to packages required in production.
• Move large data, media, and model artifacts to external storage instead of bundling them into the app.
• Audit the repository and runtime package contents deliberately so the slug stays small and deployable.