How to Containerize Python Applications with Docker

Stop fighting with "it works on my machine" and start shipping your Python apps exactly how they were intended to run.

Whether you are deploying a Flask API, a FastAPI backend, or a data processing script, Docker ensures that your environment—your OS, your Python version, and your dependencies—remains identical from your local laptop to the production server.

Here is a step-by-step guide to containerizing your Python application.

What Exactly is Containerization?

At its simplest, containerization wraps your application and everything it needs to run (libraries, system tools, runtime) into a single "image."

Unlike a Virtual Machine (VM), which bundles a full guest operating system, a Docker container shares the host's kernel. This makes containers incredibly lightweight, fast to start, and consistent across different cloud providers.

Step 1: Prepare Your Python Project

Before touching Docker, your project needs a clear way to manage dependencies. The industry standard is a requirements.txt file.

If you haven't already, generate your dependency list:

pip freeze > requirements.txt

Your project structure should look something like this:

my-python-app/
├── app.py
├── requirements.txt
└── Dockerfile

Step 2: Creating the Dockerfile

The Dockerfile is the blueprint for your image. It is a text document containing all the commands a user could call on the command line to assemble an image.

Create a file named Dockerfile (no extension) and add the following:

# 1. Use an official Python runtime as a parent image
FROM python:3.11-slim

# 2. Set the working directory in the container
WORKDIR /app

# 3. Copy the requirements file into the container
COPY requirements.txt .

# 4. Install the dependencies
RUN pip install --no-cache-dir -r requirements.txt

# 5. Copy the rest of the application code
COPY . .

# 6. Specify the command to run the app
CMD ["python", "app.py"]

Breaking Down the Instructions:

• FROM python:3.11-slim: We use the slim version of the official Python image. It contains the minimal packages needed to run Python, keeping your image size small.
• WORKDIR /app: This creates a folder inside the container where all subsequent commands will run.
• COPY requirements.txt .: We copy the requirements file first. Docker caches layers; by installing dependencies before copying the rest of the code, Docker won't need to re-install your libraries every time you change a single line of code in app.py.
• RUN pip install: This executes the installation process during the build phase.
• CMD: This tells the container which command to execute when it actually starts.

Step 3: Building the Image

Now that you have the blueprint, you need to build the image. Open your terminal in the project root and run:

docker build -t my-python-app .

• -t my-python-app: This tags your image with a friendly name.
• .: This tells Docker to look for the Dockerfile in the current directory.

Step 4: Running the Container

Once the image is built, you can launch it as a container.

For a simple script:

docker run my-python-app

For a web application (e.g., Flask or FastAPI): If your app runs on port 8000, you need to map the container's port to your machine's port:

docker run -p 8000:8000 my-python-app

Pro Tips for Better Python Containers

1. Use a .dockerignore File

You don't want to copy your virtual environment (venv), __pycache__, or .git folders into your image. This bloats the image and can cause runtime errors. Create a .dockerignore file in your root:

venv/
__pycache__/
*.pyc
.git/
.env

2. Avoid Running as Root

By default, Docker runs as the root user, which is a security risk. You can create a non-privileged user in your Dockerfile:

RUN useradd -m myuser
USER myuser

3. Use Multi-Stage Builds

For large applications, you can use "Multi-Stage Builds." You use one heavy image to compile your dependencies (building wheels) and then copy only the finished binaries into a second, ultra-slim image. This can reduce image sizes from 800MB down to 100MB.

Summary Checklist

1. requirements.txt: List your dependencies.
2. Dockerfile: Define the environment and startup command.
3. .dockerignore: Keep the image clean.
4. docker build: Create the image.
5. docker run: Execute the application.