Honcho

2.0.0 · active · verified Sat Apr 11

Honcho is a Python port of David Dollar's Foreman, a command-line application that helps you manage and run Procfile-based applications. It simplifies deployment and configuration in development and production by running multiple external processes and multiplexing their output. The current version is 2.0.0, with releases occurring infrequently but actively maintained.

Warnings

breaking Version 2.0.0 dropped support for Python 3.6, 3.7 and PyPy 3.7, 3.8. It now supports Python 3.11, 3.12, 3.13 and PyPy 3.9, 3.10.
Fix: Upgrade to a supported Python or PyPy version (3.11+ for CPython, 3.9+ for PyPy).
gotcha Be careful not to confuse `honcho` (Procfile manager) with `honcho-ai` (an unrelated AI conversational memory platform SDK). Ensure you install `honcho` from PyPI for Procfile management.
Fix: Always verify the package name when installing: `pip install honcho`.
gotcha The `honcho run` command is designed to execute arbitrary shell commands within the environment provided by Honcho and `.env` files. It does not accept Procfile-defined process targets. For running Procfile-defined processes, use `honcho start`.
Fix: Use `honcho start` to run processes defined in your Procfile. Use `honcho run <command>` for ad-hoc commands.
gotcha When using command-line arguments like `-f` (to specify a Procfile path), ensure they are placed *before* the subcommand (e.g., `start`, `run`) to be correctly parsed. Historically, placing them after the subcommand could lead to them being ignored in older versions.
Fix: Always place global options before the subcommand: `honcho -f Procfile.dev start`.
gotcha The `PROCFILE` environment variable in Honcho 2.0.0 configures the *name* of the Procfile (e.g., 'Procfile.dev'), not necessarily its full path, if you intend to override the default `Procfile` lookup behavior. While older versions mentioned specifying location, the intent is for filename overrides.
Fix: To specify a Procfile path, use the `-f` command-line argument: `honcho -f /path/to/Procfile start`. The `PROCFILE` environment variable should typically specify a filename.

Install

pip install honcho Install Honcho

Imports

Procfile
```
from honcho.lib.procfile import Procfile
```
For programmatic parsing of Procfile contents. Honcho is primarily a CLI tool; direct Python imports are less common for typical usage.

Quickstart

Create a Procfile to define your application's processes (e.g., a simple web server) and then use `honcho start` to run them. Honcho will automatically read the `Procfile` in the current directory and assign a port.

echo 'web: python -m http.server $PORT' > Procfile
honcho start

view raw JSON →