portus-py

Docker scaffolding for Python projects. Scans your project and generates a production-ready Dockerfile, .dockerignore, and docker-compose.yaml tailored to what it finds.

For Node.js projects, see Portus instead — the original, npm-published version of this tool.

Requirements

Python 3.9 or later to run portus-py itself. Docker is required separately to build and run the generated Dockerfile and docker-compose.yaml.

Installation

pip install portus-py

Usage

Preview what portus-py detects without writing any files:

portus-py scan

Generate Docker configuration for the current project:

portus-py init

This scans the repository, prints what was detected, and writes a Dockerfile, .dockerignore, and docker-compose.yaml. If any of these files already exist, you will be prompted before they are overwritten.

Skip overwrite prompts:

portus-py init --yes

What gets detected

• Package manager — resolved from lockfiles, in priority order: poetry.lock, pdm.lock, uv.lock, Pipfile.lock, requirements.txt, defaulting to plain pip if none are found.
• Python version — resolved from pyproject.toml (requires-python or Poetry's python dependency), then .python-version, then runtime.txt, defaulting to 3.12.
• Framework — Django, FastAPI, and Flask (all treated as web services), and Celery (treated as a background worker with no HTTP port or healthcheck).

Framework support

For Django, FastAPI, and Flask, portus-py inspects the actual entry-point file (manage.py, main.py, app.py) to determine the correct module path for the generated CMD, rather than guessing. When it can't confirm the app instance with high confidence, it still generates a best-effort CMD but prints a warning explaining the assumption made, so nothing fails silently.

Dockerfiles are single-stage for now — Python's packaging story doesn't lend itself to the same clean multi-stage optimization Node projects get, so this keeps the generated output simple and correct rather than fragile.

License

MIT