Docker for Python Development: Solve 'It Works on My Machine'

Why You Should Start Using Docker for Python Development Right Now

Here's a scenario many of us have faced. You're working on a Python project locally, everything runs fine. Then you push it to a server or share it with a teammate, and suddenly nothing works. Different Python versions, missing libraries, environment variables not set. It's frustrating, and it wastes hours of debugging time.

That's exactly where Docker changes the game for Python developers. Instead of fighting with virtual environments and "it works on my machine" problems, Docker lets you package your entire development environment into something portable and repeatable. Let me show you how it works in practice.

What Docker Actually Does for Python Developers

Think of Docker as a lightweight virtual machine, but much faster and more efficient. It runs your Python application in an isolated container that contains exactly what it needs—nothing more, nothing less. When you use Docker, your development environment becomes a configuration file that you can version control, share, and reproduce anywhere.

The real beauty? You can have multiple Python projects on the same machine, each running different Python versions and completely different sets of dependencies, without any conflicts. PythonSkillset contributors often work with Django apps alongside Flask microservices, and Docker makes this painless.

Setting Up Your First Python Docker Environment

Let's walk through creating a basic Python project with Docker. First, create a simple app.py:

def greet(name):
    return f"Hello, {name}! Welcome to Python development with Docker."

if __name__ == "__main__":
    print(greet("PythonSkillset reader"))

Now, here's where the magic happens. Create a file called Dockerfile (no extension) in the same directory:

# Use an official Python runtime as the base image
FROM python:3.11-slim

# Set the working directory inside the container
WORKDIR /app

# Copy the current directory contents into the container
COPY . /app

# Run the Python script when the container starts
CMD ["python", "app.py"]

That's it. The FROM line tells Docker which Python version to use. The WORKDIR creates a folder inside the container. The COPY command brings your code in. The CMD defines what runs when you start the container.

Running Your Containerized Python App

Building and running this is straightforward. Open your terminal in the project directory and run:

docker build -t python-skillset-app .
docker run python-skillset-app

You'll see the greeting message appear. What just happened? Docker downloaded the official Python 3.11 image, created a container with your code inside, ran it, and printed the output. The entire process took seconds, and your host machine stayed completely clean.

Handling Dependencies the Docker Way

Real projects have dependencies. PythonSkillset uses requirements.txt for managing packages. Here's how Docker handles that:

Update your Dockerfile to include dependency installation:

FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . /app
CMD ["python", "app.py"]

Notice the order. We copy requirements.txt first and install dependencies before copying the rest of the code. This is intentional—Docker caches layers, so if you only change your application code, Docker reuses the already-built dependency layer, making rebuilds much faster.

Your requirements.txt might look like this:

flask==2.3.3
requests==2.31.0
python-dotenv==1.0.0

Now your container has exactly those packages, no more, no less. No conflicts with other projects on your machine.

Development Workflow with Docker

For active development, you don't want to rebuild the container every time you change code. Docker supports volume mounting, which maps a folder from your host into the container. Your edits appear instantly inside the container.

Run your container for development like this:

docker run -v $(pwd):/app python-skillset-app

The -v flag mounts your current directory into /app inside the container. Now you can edit code on your machine, and the container sees the changes immediately. PythonSkillset developers use this constantly for rapid iteration.

Docker Compose for Multi-Service Projects

When your Python project needs a database or a cache, Docker Compose simplifies everything. Create a docker-compose.yml file:

version: '3.8'
services:
  web:
    build: .
    ports:
      - "5000:5000"
    volumes:
      - .:/app
    depends_on:
      - db
  db:
    image: postgres:15
    environment:
      POSTGRES_DB: pythonskillset
      POSTGRES_USER: user
      POSTGRES_PASSWORD: password

Run docker-compose up, and both your Python app and PostgreSQL start together. The app can connect to the database using the service name db as the hostname. This is how PythonSkillset handles development environments with databases, caches, and other services.

Common Pitfalls and How to Avoid Them

Your first Docker Python setup might hit a few snags. Here's what to watch for:

Permission issues with mounted volumes on Linux. Files created inside the container might be owned by root. Add a user to your Dockerfile:

RUN useradd -m -u 1000 pythonskillset
USER pythonskillset

Forgetting to rebuild after changing dependencies. If you add a package to requirements.txt, run docker build again. Simply restarting the container won't pick up new packages.

Using the wrong base image. Alpine images are tiny but can cause issues with some Python packages that need compilation. Stick with slim variants for compatibility.

The .dockerignore file is your friend. Similar to .gitignore, it prevents unnecessary files from being copied into the image. PythonSkillset always includes this:

__pycache__
*.pyc
*.pyo
.git
.env

Why This Matters for Your Python Career

Docker skills are no longer optional for professional Python development. Every deployment pipeline, every cloud service, every team collaboration benefits from containerization. When you master Docker for Python, you're not just learning a tool—you're adopting a workflow that saves you and your team countless hours.

The best part? Once you have the basics down, you can add complexity gradually. Start with simple containers, then move to multi-service setups, then to production deployments. PythonSkillset has resources for each step of that journey.

Give Docker a try on your next Python project, even a small one. The first time you set up a new machine and have your entire environment running in one command, you'll wonder how you ever worked without it.