9 min read
How to Deploy a Python App in Docker: Full Guide
Key takeaways
- One Dockerfile pattern covers Flask, Django, and FastAPI: a slim base image, cached pip install, and a gunicorn or uvicorn command bound to 0.0.0.0.
- Binding to 127.0.0.1 instead of 0.0.0.0 is the most common reason a container builds fine locally but serves nothing in production.
- A .dockerignore listing .git, venv, and pycache keeps build context small and keeps secrets out of your image.
- For solo developers, a git-push PaaS or a registry plus a cheap VPS beats Kubernetes, which adds ops overhead most side projects never need.
- Django apps need collectstatic at build time and migrations at deploy time, while FastAPI swaps gunicorn's sync worker for uvicorn or UvicornWorker.
To deploy python app in docker, write one Dockerfile that runs your app with gunicorn or uvicorn on port 8080 bound to 0.0.0.0, test it locally with docker run, then push the image or repo to a PaaS that gives you a git-push-to-deploy path with automatic HTTPS. This guide covers that full path for Flask, Django, and FastAPI.
What does it mean to deploy a Python app in Docker?
Deploying a Python app in Docker means packing your code, its Python version, and every dependency into a single image that runs identically on your laptop and on a server. You write a Dockerfile, build it, and hand the resulting container to a host instead of installing packages over SSH and hoping nothing drifts.
Why bother? Bare-metal deploys break when the server's Python or system libraries differ from yours, and they make rollback painful. A container fixes both, and it is the format most modern hosts accept: git push to deploy platforms like Render and Omeganodes build your repo into an image for you. The Dockerfile reference is the source of truth for the syntax.
The payoff is a live HTTPS URL from one repeatable artifact, not a pile of setup scripts. The same pattern carries from a side project to your first paying SaaS users.
How do you write a production Dockerfile for a Python web app?
The shared Dockerfile pattern
One Dockerfile pattern covers Flask, Django and FastAPI. Copy this and adjust the last two lines:
FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
EXPOSE 8000
CMD ["gunicorn", "-w", "2", "-b", "0.0.0.0:8000", "app:app"]
Every line earns its place. python:3.12-slim keeps the image under a few hundred MB instead of the full image's 1 GB-plus. Copying requirements.txt before the rest of the code means Docker caches your installed dependencies and skips reinstalling them on every code change.
Binding to 0.0.0.0 matters more than it looks: bind to 127.0.0.1 and your container will build fine, pass local tests, then serve nothing when deployed, because nothing outside the container can reach it. For Django, swap the CMD to gunicorn myproject.wsgi; for FastAPI, use uvicorn app:app --host 0.0.0.0 --port 8000. This is the same pattern Omeganodes expects when you push a repo with a Dockerfile, and it is what lets one file serve all three frameworks without Kubernetes or YAML files to maintain.
Why slim base images and .dockerignore matter
Add a .dockerignore next to your Dockerfile and list __pycache__, .git, venv, and .env. Without it, Docker sends your whole folder as build context, so each git push to deploy uploads megabytes you never needed and risks copying secrets into the image. Slim images plus a lean context mean faster builds, smaller deploys, and cheaper bandwidth, which counts when you are paying in shillings or cedis for data.
How do you deploy a Flask app in Docker step by step?
The Flask app and requirements.txt
Start with the smallest possible project: three files in one folder.
app.py
from flask import Flask
app = Flask(__name__)
@app.route("/")
def home():
return "Flask in Docker is live"
if __name__ == "__main__":
app.run(host="0.0.0.0", port=8000)
requirements.txt
flask==3.0.3
gunicorn==22.0.0
Dockerfile
FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
CMD ["gunicorn", "-b", "0.0.0.0:8000", "app:app"]
Gunicorn is the production server here. It binds to 0.0.0.0 so the container accepts connections from outside itself, not just localhost. The Gunicorn docs cover the -b flag and worker settings in detail.
Build and run the container
From the project folder, run:
docker build -t flask-app .
docker run -p 8000:8000 flask-app
The -p 8000:8000 maps your machine's port 8000 to the container's port 8000. Open http://localhost:8000 and you should see the response string. If you want this same image live on an HTTPS URL without touching servers, a push-to-deploy platform like Omeganodes handles the build from your repo (why we built it).
What changes for Django and FastAPI apps in Docker?
The Dockerfile pattern stays the same. Three details change: the command that starts your server, the module path you point it at, and a couple of Django-only build steps.
Django specifics
Django runs through WSGI, so your CMD targets the module containing wsgi.py, usually myproject.wsgi:application. If you use Gunicorn, the command looks like gunicorn myproject.wsgi:application --bind 0.0.0.0:8000. Two build-time additions: run python manage.py collectstatic --noinput so static files land in STATIC_ROOT, and bake python manage.py migrate into your release step rather than the image build, since migrations belong at deploy time against a live database. Set DJANGO_SETTINGS_MODULE and ALLOWED_HOSTS as environment variables so one image works across staging and production.
FastAPI specifics
FastAPI is ASGI, so swap Gunicorn's sync worker for Uvicorn: uvicorn main:app --host 0.0.0.0 --port 8000. The module path is filename:app, not a dotted WSGI path, and a typo there is the most common startup failure. If you want worker processes, use gunicorn -k uvicorn.workers.UvicornWorker main:app.
Either framework deploys the same way once the image builds: push the repo to Omeganodes and it runs the container, handles HTTPS, and gives you a URL, with no Kubernetes or YAML.
How do you run and test your Dockerized Python app locally?
Build once, then run the same image you plan to push:
docker build -t myapp .
docker run -p 8000:8000 myapp
Open http://localhost:8000 in your browser or hit it with curl. If the page loads, the container serves traffic exactly as it will on a host like Omeganodes or the platforms compared at our Ziploy comparison.
Running on Windows and macOS
Docker Desktop handles both, but watch the port flag: -p 8000:8000 maps host to container, and the order trips people up. On Windows, run commands from PowerShell or WSL, and make sure the file uses LF line endings or shell scripts inside the container will fail. On macOS with Apple Silicon, images build as ARM by default; add --platform linux/amd64 if your host runs x86 servers.
Checking logs and health
Run docker logs -f myapp to follow output and spot startup errors fast. For FastAPI, confirm your bind address: --host 0.0.0.0 is required inside a container, or nothing outside it connects, per the Uvicorn documentation.
How do you push a Dockerized Python app to a hosting platform?
You have three realistic paths: a git-push PaaS that builds your image for you, a registry plus a VPS you manage yourself, or Kubernetes. For a solo developer running a side project or first SaaS app, Kubernetes is overkill: you would spend more time on ingress controllers and node pools than on your app. Hacker News threads on Heroku alternatives keep circling the same point: people want someone else to handle routing, TLS, and restarts.
Git-push PaaS vs registry + VPS vs Kubernetes
| Path | What you do | Best when |
|---|---|---|
| Git-push PaaS | git push, platform builds and deploys | Solo devs, no infra maintenance |
| Registry + VPS | Push image to a registry, run it on a $5 server | You want full control and lowest cost |
| Kubernetes | Manifests, clusters, YAML | Teams with dedicated ops capacity |
Whichever path you choose, add a .dockerignore before your first push so build context stays small and secrets stay out of the image. The Docker build context docs cover the syntax.
Paying from East Africa: mobile money and regional pricing
The catch for many Kenyan and Ugandan developers is not deploying, it is paying. Render, Railway, and Fly.io all bill in USD by card, which locks out MTN Mobile Money and Airtel Money users who have no international card. That means the deploy works perfectly, the image builds, the URL goes live, and then the trial ends and you cannot hand over a payment method the platform accepts. Before you commit to any host, check the payment methods page first, because a PaaS you cannot pay for is not an alternative no matter how good its free tier looks. Regional-priced options that accept mobile money close this gap, and the fair-price question matters as much as the deploy question. If your card works, ignore this section entirely; if it does not, filter your platform search by payment method before you filter by features, uptime, or framework support.
Why won't my Python Docker container start or serve traffic?
Port binding: 0.0.0.0 vs 127.0.0.1
The container builds fine, the platform says it's live, but the URL times out. Nine times out of ten your app is listening on 127.0.0.1 inside the container, so nothing outside can reach it. Bind to 0.0.0.0 and the container's port instead: gunicorn -b 0.0.0.0:8000 or uvicorn main:app --host 0.0.0.0 --port 8000. Then check that your EXPOSE and platform port settings match. Most PaaS providers, including Omeganodes, inject a PORT variable — read it rather than hardcoding 8000.
Missing gunicorn or uvicorn in the image
The app runs locally with flask run or uvicorn, then crashes in production with "command not found". Your dev server tool was never installed in the image. Add gunicorn or uvicorn to requirements.txt and set the start command in your Dockerfile's CMD or ENTRYPOINT. Never rely on the platform guessing the command.
Shrinking a bloated image
A 2 GB image slows every deploy and can exceed platform limits. Pin a slim base like python:3.12-slim, copy requirements first so pip layers cache, and add a .dockerignore for .git, venv and __pycache__. Multi-stage builds (build wheels in one stage, copy them into a clean stage) typically cut the final image by more than half.
FAQ
Can I deploy a Python app in Docker without a credit card?
Yes, but your options narrow. Most major platforms, including Render, Railway, and Fly.io, bill in USD by card, which excludes developers paying with MTN Mobile Money or Airtel Money. Look for hosts with regional pricing that accept mobile money, or run the image yourself on a VPS you rent with a local payment method.
How much RAM does a Dockerized Python app need in production?
A small Flask or FastAPI container with Gunicorn or Uvicorn runs comfortably in 256 to 512 MB. Django with migrations and static files typically wants 512 MB or more. Add headroom for worker processes: each Gunicorn worker holds its own memory, so two workers roughly double the footprint of one.
Do I need Kubernetes to deploy a Dockerized Python app?
No. For a solo developer or a first SaaS app, Kubernetes is overkill: you would spend more time on ingress controllers and node pools than on your app. A git-push PaaS that builds your Dockerfile, or a registry plus a cheap VPS, covers everything most side projects and early products need.
How do I connect a custom domain and HTTPS to my Docker container?
Point your domain's DNS records at your host, then let the platform handle certificates. Most git-push PaaS providers issue and renew TLS certificates automatically once the domain verifies. On a VPS you manage yourself, you run the certificate setup and renewal yourself, typically with a reverse proxy in front of the container.
Can I deploy a Python Docker app from Windows?
Yes. Docker Desktop handles builds on Windows, but run commands from PowerShell or WSL and make sure files use LF line endings, or shell scripts inside the container will fail. Remember that -p 8000:8000 maps host port to container port, an order that trips up plenty of first-time deploys.
Deploy at the speed of Africa
World-class hosting, open to every developer, wherever you build and however you pay. Start free in a couple of minutes — no credit card, no lock-in.