🚀 How to dockerize Flask app with virtualenv

🐍 Virtualenv — Why It Matters

A virtual environment isolates a Python project's dependencies from the system interpreter, preventing version clashes and ensuring reproducible builds. The isolation step is also the foundation for a reliable Docker image.

📑 Table of Contents

• 🐍 Virtualenv — Why It Matters
• 📦 Dockerfile — Building the Image to Dockerize
• 🚀 Gunicorn — Production WSGI Server
• ⚙️ Worker Types — Choosing the Right Model
• 🔧 Running Gunicorn Inside Docker
• 🛠 Compose — Orchestrating Multiple Containers Together
• 🟩 Final Thoughts
• ❓ Frequently Asked Questions
• How do I expose additional environment variables to the Flask container?
• Can I use a different base image, such as Alpine, instead of python:3.11-slim?
• What is the recommended number of Gunicorn workers for a CPU‑bound Flask app?
• 📚 References & Further Reading

📦 Dockerfile — Building the Image to Dockerize

This Dockerfile builds a minimal image that bundles the virtual environment and runs the Flask service with Gunicorn.

# Dockerfile
FROM python:3.11-slim # Install system build tools (minimal for pip wheels)
RUN apt-get update && apt-get install -y -no-install-recommends \ gcc libpq-dev && rm -rf /var/lib/apt/lists/* # Create a non‑root user to run the app
RUN useradd -m appuser
WORKDIR /app # Copy only the requirement list first to leverage Docker cache
COPY requirements.txt .
RUN python -m venv venv \ && . venv/bin/activate \ && pip install -no-cache-dir -r requirements.txt # Copy the source code
COPY . . # Switch to non‑root user
USER appuser # Default command runs Gunicorn via the virtualenv
CMD ["/app/venv/bin/gunicorn", "-w", "4", "-b", "0.0.0.0:8000", "app:app"]

What this does:

• FROM python:3.11-slim : starts from an official slim image, keeping the base size low (≈ 30 MB).
• RUN apt-get … : installs only the compile‑time libraries needed for native wheels, avoiding unnecessary runtime packages.
• python -m venv venv : creates an isolated environment inside the image.
• . venv/bin/activate && pip install -no-cache-dir -r requirements.txt: ensures pip writes packages to venv, and the --no-cache-dir flag prevents extra layer bloat.
• CMD … : launches the production WSGI server directly from the virtualenv, guaranteeing version consistency.

Separating the dependency installation from the source copy allows Docker to cache the pip install step. Subsequent code changes rebuild only the final layers, reducing rebuild time from minutes to seconds.

According to the official Docker documentation, building images with a clear separation between dependency installation and source copy maximizes cache efficiency and reduces rebuild times.

Key point: The Dockerfile embeds the virtual environment, so the resulting image can be built on any host without requiring a pre‑existing Python environment.

---

🚀 Gunicorn — Production WSGI Server

Gunicorn implements a pre‑fork worker model that balances request handling across multiple processes, offering higher concurrency than Flask’s built‑in server.

⚙️ Worker Types — Choosing the Right Model

Gunicorn provides several worker classes. The default sync workers use a single thread per process, which is optimal for CPU‑bound workloads. For I/O‑bound applications, gevent (greenlet‑based) or uvicorn.workers.UvicornWorker (asyncio) can improve throughput by allowing a single worker to handle many concurrent connections.

$ docker run -rm flask-app:latest gunicorn -workers 2 -worker-class sync -help
usage: gunicorn [OPTIONS] APP_MODULE Options: -w, -workers INT The number of worker processes for handling requests. -worker-class STRING The type of workers to use (sync, gevent, etc.). -b, -bind ADDRESS The socket to bind.
...

Gunicorn’s multi‑process model prevents the single‑threaded bottleneck of Flask’s development server, reducing latency under load.

🔧 Running Gunicorn Inside Docker

The CMD defined in the Dockerfile launches Gunicorn from the virtual environment. Verify that the process starts correctly by building and running the container locally. (Also read: ⚙️ FastAPI vs Flask for async microservices — which one should you actually use?) (More onPythonTPoint tutorials)

$ docker build -t flask-app .
Sending build context to Docker daemon 4.096kB
Step 1/12: FROM python:3.11-slim
...
Successfully built a1b2c3d4e5f6
Successfully tagged flask-app:latest $ docker run -d -p 8000:8000 flask-app
c3d4e5f6a7b8c9d0e1f2g3h4i5j6k7l8m9n0o1p2q3r4s5t6u7v8w9x0y1z2 $ docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
c3d4e5f6a7b8 flask-app "/app/venv/bin/gunico…" 2 seconds ago Up 1 second 0.0.0.0:8000->8000/tcp nostalgic_mestorf

The container reports Gunicorn listening on 0.0.0.0:8000, confirming that the virtualenv‑based command works as intended. (Also read: 🐍 Azure App Service vs AKS for Django deployment — which one should you use?)

Key point: Running Gunicorn from the virtual environment guarantees that the exact version defined in requirements.txt is used, eliminating mismatch‑related runtime errors.

---

🛠 Compose — Orchestrating Multiple Containers Together

Docker Compose describes a multi‑service application, allowing the Flask container to be paired with a database or cache without manual networking.

# docker-compose.yaml
version: "3.9"
services: web: build: . ports: - "8000:8000" environment: - FLASK_ENV=production depends_on: - db db: image: postgres:15-alpine environment: POSTGRES_USER: flask_user POSTGRES_PASSWORD: secretpassword POSTGRES_DB: flask_db volumes: - pgdata:/var/lib/postgresql/data
volumes: pgdata:

What this does:

• build: . : tells Compose to use the Dockerfile in the current directory.
• depends_on : ensures the database container starts before the Flask container attempts a connection.
• volumes : persists PostgreSQL data across container restarts.

Compose abstracts networking, assigns each service a DNS name (e.g., db), and manages the lifecycle of related containers as a unit, which is essential for realistic development and testing.

Start the stack and verify that both containers are healthy.

$ docker-compose up -d
Creating network "project_default" with the default driver
Creating volume "project_pgdata" with local driver
Creating container project_db_1 ... done
Creating container project_web_1 ... done $ docker-compose ps Name Command State Ports -------------------------------------------------------------------------------
project_db_1 docker-entrypoint.sh postgres Up 5432/tcp
project_web_1 /app/venv/bin/gunicorn -w 4 ... Up 0.0.0.0:8000->8000/tcp

At this point the Flask API is reachable at http://localhost:8000, and it can communicate with the PostgreSQL service via the hostname db.

Running the same Flask code inside a container, isolated by a virtualenv, eliminates “works on my machine” errors.

---

🟩 Final Thoughts

Dockerizing a Flask app with virtualenv produces a reproducible artifact that can move between development, staging, and production without code changes. The virtual environment guarantees that the exact dependency graph defined in requirements.txt is used, while Gunicorn provides a battle‑tested WSGI server that scales beyond the single‑threaded development server. Adding Docker Compose turns a single service into a full‑stack development environment, enabling local testing of database interactions before any code reaches production. By separating concerns—environment isolation, container image definition, and process management—you gain both security (non‑root user, minimal base image) and operational stability (layer caching, deterministic builds). This pattern scales from a single‑container prototype to a multi‑service production deployment with minimal adjustments.

Adopting the pattern now means future Flask projects can start from a proven baseline, reducing onboarding friction and cutting the time spent debugging environment mismatches.

❓ Frequently Asked Questions

How do I expose additional environment variables to the Flask container?

Declare them under the environment section of docker-compose.yaml or pass -e VAR=value to docker run. They become available to the Python process via os.getenv.

Can I use a different base image, such as Alpine, instead of python:3.11-slim?

Yes, but Alpine uses musl instead of glibc, which can cause binary‑wheel incompatibilities for some packages. If you switch, rebuild the virtual environment inside the image to ensure all compiled extensions match the target libc.

What is the recommended number of Gunicorn workers for a CPU‑bound Flask app?

Start with 2 × CPU cores + 1 workers. This formula balances CPU utilization and context‑switch overhead. Adjust based on observed latency and throughput metrics.

💡 Want to practise this hands-on? DigitalOcean gives new accounts $200 free credit for 60 days — enough to spin up a full Linux/Docker/Kubernetes environment at no cost.

📚 Recommended reading: Best DevOps & cloud books on Amazon — from Linux fundamentals to Kubernetes in production, curated for working engineers.

📚 References & Further Reading

• Official Flask documentation — core concepts and application factory pattern: flask.palletsprojects.com
• Docker documentation — best practices for building images and using multi‑stage builds: docs.docker.com