Procfile: definition and meaning

A Procfile is a text file named Procfile that declares an app’s process types, one per line, as a type name, a colon, and the command that runs it. Heroku defines the format, and local runners such as Foreman read it too.

Updated

A Procfile is a text file that lists the processes an app runs, one per line. Each line has a process type, a colon, and the command that starts it. Heroku defines the format, and local runners such as Foreman read the same file.

Format

The file is named Procfile, with a capital P and no extension, and it sits in the root directory of the app. Each line has this shape:

Text
<process type>: <command>

A small example:

Text
web: node server.js
worker: node jobs/queue.js
release: node scripts/migrate.js

On Heroku, web is the only process type that can receive HTTP traffic from the platform’s routers, so a web process has to listen on the port Heroku gives it in the PORT environment variable. The release type is also special: it names a command that Heroku runs in a one-off dyno for a new release, and the app’s dynos do not boot for that release until the command succeeds. Other names, such as worker, have no special meaning and are free labels for background processes.

Using one locally

Outside Heroku, a Procfile is a list of things to start together. Foreman, for example, runs one instance of each process type in the file and interleaves their output on standard output. That makes it a convenient way to describe an app with a web server, a queue worker, and an asset watcher without opening three terminal tabs. A runner may accept a different file name. Foreman takes one with its -f option:

Terminal
foreman start -f Procfile.dev

Do not assume a local runner copies all of Heroku’s behaviour. Heroku’s own heroku local command, for instance, does not run the release process type.

A common confusion

A Procfile is a convention, not a standard. Heroku defines the format and the meaning of its special names, and every other tool decides for itself what to accept. Whether the name web matters depends on the tool reading the file. Locally, any process type can be the one that serves requests, whatever it is called.

A Procfile also says only what to run. It does not install dependencies or build assets, and a file called Procfile.dev is invisible to any tool that looks for Procfile.

In Rig

Rig reads a file named exactly Procfile in the project root. Procfile.dev and other names are not read.

  • Each line must match name: command, where the name uses letters, digits, underscores, and hyphens. Rig skips blank lines and lines that start with #. Continuation lines are not supported.
  • Every process type becomes a script you can pick for the project. Rig marks a process type as recommended when it looks like a server.
  • Rig runs the command with /bin/sh -c, or with cmd.exe /d /s /c on Windows.
  • If the project has a port set, Rig appends --port N to the command and exports PORT, VITE_PORT, HOST_PORT, and npm_config_port. A command that does not accept --port still receives it, so check how your command handles the extra argument.
  • Environment variables come from the project’s active env profile.

Related terms

Sources

  1. Heroku Dev Center: The ProcfileOfficial documentation, checked 13 October 2026
  2. Heroku Dev Center: Release PhaseOfficial documentation, checked 13 October 2026
  3. Heroku Dev Center: Runtime PrinciplesOfficial documentation, checked 13 October 2026
  4. Heroku Changelog: Heroku local no longer runs the release process typeOfficial documentation, checked 13 October 2026
  5. foreman(1): manage Procfile-based applicationsOfficial documentation, checked 13 October 2026
  6. Rig documentation: Procfile projects (parser behaviour confirmed in Rig’s source code)Rig source code, checked 13 October 2026

Related reading

See how Rig fits in

Rig is a Mac app that starts, stops, and watches the processes in a project from one window. The knowledge base explains each part in plain language.

Read what Rig is

Related

https://userig.app/glossary/procfile