Skip to content
Tutorials Center
My learning

Topics

Lesson 7 of 37 ยท Apps, Dynos and Buildpacks

Procfile and Process Types

Learn the Heroku Procfile format, the special web and release process types, how to add worker and clock processes, and how to scale each type independently.

Heroku needs to know what command to run in a dyno. Sometimes a buildpack guesses (the Node.js buildpack runs npm start), but real apps almost always declare it explicitly in a file called Procfile. A Procfile is a plain text file at the root of your repository that maps process types to commands. It is one of the smallest files in a project and one of the most important.

The format

Each line is a process type name, a colon, a space and the command:

TEXT
web: gunicorn config.wsgi --log-file -
worker: python manage.py run_queue_worker
clock: python scheduler.py
release: python manage.py migrate

The rules, which trip up beginners more than anything else:

  • The file must be named exactly Procfile, with a capital P and no extension.
  • It must be in the root of the repository you push, and committed.
  • The type name may contain letters, digits and underscores, and is followed by : (a colon and a space).
  • Each line is one command, run through a shell, so environment variable expansion such as $PORT works.
  • Blank lines and lines that do not match the format are ignored, so a typo makes a process silently missing rather than loudly broken.

Process types

A process type is a role, and the name is up to you except for a few that Heroku treats specially.

  • web is the only type that receives HTTP traffic from the router. It must bind to $PORT.
  • release is run once per deploy, before the new release goes live, and a failure cancels the release. It is the right place for database migrations. See release phase and migrations.
  • worker (a convention, not magic) runs background jobs from a queue. It receives no traffic, so it needs no port.
  • Anything else (clock, urgentworker, scheduler) is a name you choose. You scale it like any other type.
flowchart TB
  P["Procfile"] --> W["web<br/>receives HTTP"]
  P --> K["worker<br/>pulls jobs"]
  P --> C["clock<br/>runs timers"]
  P --> R["release<br/>runs once per deploy"]

One file, several roles. Only web gets routed traffic, and release runs outside the normal dyno formation.

A common beginner mistake is to run web, worker and scheduler inside one process with a supervisor. It works, but you cannot scale them separately, and a worker crash can take the web server down. Separate process types give you separate dynos, separate scaling and separate logs.

Scaling each type

Once your Procfile declares types, you decide how many dynos of each to run:

CONSOLE
$ heroku ps:scale web=2 worker=1 clock=1
$ heroku ps:scale worker=0

Scaling a type to 0 stops it without deleting the definition, which is a handy way to pause a worker while you investigate a problem. The result of all your scale commands is the app's formation. After a fresh deploy, Heroku creates one web dyno from your Procfile and zero of every other type, so a worker line does nothing until you scale it up.

Dyno names follow the pattern TYPE.N: web.1, web.2, worker.1. You see these names in heroku ps and in the log stream.

A concrete Procfile for a few languages

The command depends on the language and web server, but the shape is the same:

TEXT
# Node.js
web: node server.js
worker: node worker.js

# Python (Django + gunicorn)
web: gunicorn mysite.wsgi
worker: celery -A mysite worker --loglevel=info

# Ruby on Rails
web: bundle exec puma -C config/puma.rb
worker: bundle exec sidekiq
release: bundle exec rails db:migrate

Notice that none of these hard-code a port. Frameworks such as gunicorn and puma read PORT from the environment, or you pass it explicitly (for example gunicorn -b 0.0.0.0:$PORT app:app).

Tip: heroku local reads the same Procfile and starts all the processes on your own computer, with logs from each color-coded. It is a fast way to prove the file works before you deploy. See Heroku Local and env files.

Stand-in: parse a Procfile

A parser makes the format rules concrete. This stand-in applies the same line rule described above and reports what it ignored, which is the situation behind many "my worker never starts" questions.

Python Stand-in: read a Procfile

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.

The clock line misses its colon, so it is not recognized, and the comment line is ignored too. The real platform quietly skips bad lines in the same spirit, so always check heroku ps after a deploy.

Stand-in: plan a formation

A formation is the answer to "how many dynos of each type?" This stand-in totals the dynos and warns about a mistake that is easy to make: scaling a type that is not in the Procfile.

Python Stand-in: validate a scale request

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.

Common mistakes

Mistake Effect
File called procfile or Procfile.txt Ignored; the buildpack default is used or the app has no web process
Procfile not committed Not in the slug; git status before you push
Missing space after the colon The line is skipped
web: binds a fixed port Boot timeout (R10)
Worker defined but never scaled The queue fills up and nothing consumes it

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which process type is the only one that receives HTTP traffic from the router?

    Only dynos of the web type are routed requests. Other types, such as worker, handle background work.
  2. 2. Where must the Procfile be?

    The platform reads Procfile from the root of the pushed repository. The name is case sensitive.
  3. 3. What does a release process type do?

    The release command runs between build and release. A failure stops the new release from going live.
  4. 4. After deploying with web and worker lines, how many worker dynos run by default?

    Heroku starts one web dyno by default; other process types stay at zero until you run heroku ps:scale.
  5. 5. A Procfile line reads clock python scheduler.py. What happens?

    Lines that do not match the 'type: command' format are skipped, so the clock process never exists.

Summary

  • A Procfile maps process types to commands; it lives in the repository root and is case sensitive.
  • web receives HTTP, release runs on deploys, and other names are roles you invent, such as worker and clock.
  • Each type scales independently with heroku ps:scale; types other than web start at zero dynos.
  • Bad lines are silently ignored, so verify with heroku ps and heroku local.

Next: Buildpacks