Skip to content
Tutorials Center
My learning

Topics

Lesson 16 of 37 ยท Add-ons and Config

Heroku Local and .env Files

Run your Procfile processes on your own computer with heroku local, load settings from a .env file, keep secrets out of Git, and mirror production behavior while developing.

Deploying to find out whether your Procfile works is slow and noisy. It is much nicer to prove it on your own machine first, with the same process types and the same style of configuration you will use in production. The heroku local command does exactly that: it reads your Procfile, loads variables from a .env file, starts every process and merges their output into one window.

This lesson covers how heroku local works, what belongs in a .env file (and what does not), and how to keep local and production behavior close.

Running locally

From the root of your project:

CONSOLE
$ heroku local
$ heroku local web
$ heroku local web=2,worker=1
$ heroku local -p 5001
$ heroku local -f Procfile.dev
$ heroku local -e .env.test
  • Without arguments it starts every process type in the Procfile (except release) with one process each.
  • heroku local web starts only the web type; web=2 starts two copies (on consecutive ports).
  • -p sets the base port (the default is 5000), -f chooses another Procfile such as a development-only one, and -e chooses another env file.
  • heroku local:run COMMAND runs a one-off command with the .env loaded, which is the local twin of heroku run: heroku local:run python manage.py migrate.

Each line of output is prefixed with the process name and colored, so a web request and a worker job are easy to tell apart. Stop everything with Ctrl+C. Because it runs on your computer, it uses your installed runtimes, so pin the same language versions you use in production.

heroku local is not a perfect copy of the platform: your OS differs from the stack, the filesystem is persistent, and nothing enforces memory limits. It checks that the commands and the config are wired correctly, not that production will behave identically. For stronger parity, run your Docker image locally if you deploy containers.

The .env file

heroku local reads variables from a file named .env in the project root. The format is the familiar KEY=value per line:

TEXT
# development settings
DEBUG=true
SECRET_KEY=dev-only-not-secret
DATABASE_URL=postgres://dev:dev@localhost:5432/shop_dev
GREETING="Hello, world"
export LOG_LEVEL=debug

Common rules (most dotenv implementations agree, though details vary slightly between tools):

  • Lines starting with # are comments, and blank lines are ignored.
  • Values may be quoted with single or double quotes; quotes protect spaces.
  • An optional leading export is tolerated.
  • There is no list or number type: everything is a string, like the real environment.

Never commit .env

The file contains local secrets, and it differs on every developer's machine. Add it to .gitignore, and commit a template instead:

TEXT
# .env.example (committed): copy to .env and fill in
DEBUG=true
SECRET_KEY=
DATABASE_URL=postgres://localhost/shop_dev

New teammates run cp .env.example .env and know exactly which variables to provide. The template documents the app's configuration surface, and a missing-variable error at boot (see config vars) tells them which one they forgot.

Pulling production config down

You can copy real settings into a local file:

CONSOLE
$ heroku config --shell -a demo-shop > .env

Be careful: that puts production secrets on your laptop, and your local code might then talk to the production database. Prefer local development credentials and only copy the non-secret settings you need.

Stand-in: a .env parser

The parser below follows the rules above. Real tools (such as the dotenv libraries) handle more edge cases, such as multi-line values and escapes, so treat this as a model of the idea.

Python Stand-in: parse .env text

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Notice that the quoted value keeps its #, an unquoted comment line is skipped and the malformed line is reported instead of silently ignored.

Stand-in: start processes and prefix their output

heroku local shows several processes in one stream, each with its name in front. This stand-in does the same with fake output so you can see why the prefixes matter when two processes talk at once.

Python Stand-in: interleaved process output

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Local parity checklist

  1. Run heroku local before every first deploy of a new Procfile.
  2. Use the same language versions locally and in production.
  3. Keep .env.example current whenever you add a variable.
  4. Use local databases and local test API keys, not production ones.
  5. Test the release command by hand locally (heroku local:run python manage.py migrate), because heroku local does not run it for you.

Do not commit .env. If you ever did, rotate every secret it contained. Add .env to .gitignore before the first commit, and consider a pre-commit secret scanner.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does heroku local read to know which processes to start?

    heroku local starts the process types defined in the Procfile, loading variables from .env.
  2. 2. Which file should be committed to document required settings?

    .env.example lists the variables with safe placeholders, while the real .env stays out of Git.
  3. 3. What is the default base port for heroku local?

    heroku local assigns PORT starting at 5000 unless you pass -p.
  4. 4. Why is copying production config into .env risky?

    Local experiments could damage production data, and a stolen laptop would leak real secrets.

Summary

  • heroku local runs your Procfile processes locally with output merged and prefixed.
  • .env holds local settings as KEY=value lines; keep it out of Git and commit .env.example instead.
  • Use -p, -f and -e to change port, Procfile and env file, and local:run for one-off commands.
  • Local runs check wiring, not full production parity.

Next: Add-ons overview