Containerize Python with Docker on ECR

Your Python app runs perfectly on your laptop. Push it to a server, and suddenly it crashes because someone installed the wrong version of a library, or the OS is missing a system dependency. This "works on my machine" problem is the #1 cause of deployment failures in real-world DevOps. Docker solves that by packaging your app, its dependencies, and its runtime into a single, immutable artifact — a container image. In this lesson, you'll learn how to containerize a Python app with Docker on ECR, the AWS container registry, so you can deploy that image anywhere on AWS with total consistency.

The problem this lesson solves

Imagine you're a DevOps engineer. You've just finished a Flask web app that uses Redis and a custom Python package. You hand it to the ops team, but their Linux box has Python 3.6, your app needs 3.11. The Redis client is missing, and someone installed a conflicting version of requests. Deployment becomes a nightmare of manual fixes.

Docker eliminates this entire class of problems. By containerizing your Python app, you create a self-contained image that includes your code, all Python dependencies (from pip), and the base OS layer. When you push that image to Amazon ECR (Elastic Container Registry), you have a single, versioned artifact that can be pulled and run on any Docker-compatible host — EC2, ECS, EKS, or even your local machine. This is the foundation of modern CI/CD pipelines, so mastering it is essential for any cloud developer.

Core concept / mental model

Think of a container image as a shipment box for your app. Inside the box, you have everything needed to run: a tiny Linux OS, Python interpreter, your source code, and all third-party libraries. Docker is the packing factory — it uses a Dockerfile as the instruction manual for exactly how to build that box.

ECR is the warehouse where you store these boxes. Instead of physically moving them, you push your image to ECR and later pull it on any server. Each image has a unique tag (like v1.0.0 or latest) so you can keep multiple versions and roll back instantly.

Here's the mental map:

• Dockerfile → defines how to build the image (the recipe).
• docker build → executes the recipe and produces an image.
• docker push → uploads the image to ECR.
• docker pull → downloads the image to a deployment target.
• ECR → private or public registry that stores your images securely.

How it works step by step

Containerizing a Python app with Docker on ECR is a linear process. Here's the logical flow:

1. Write a Dockerfile in your project root. This file defines the base image (e.g., python:3.11-slim), copies your code, installs dependencies, and sets the command to run your app.
2. Build the image locally with docker build -t my-app . to verify it works.
3. Create an ECR repository in your AWS account to hold your images.
4. Authenticate Docker to your ECR registry using the aws ecr get-login-password command.
5. Tag your image with the ECR repository URI.
6. Push the image to ECR.
7. Optionally test by pulling the image and running a container from it.

Each step has a cause-and-effect: a well-formed Dockerfile yields a reproducible build; correct authentication gives push access; a versioned tag enables rollbacks.

Hands-on walkthrough

Let's containerize a simple Python Flask app. You'll need Docker installed and the AWS CLI configured with credentials that have ECR permissions.

Step 1: Create a minimal Flask app

First, create a project folder and add these files:

# app.py
from flask import Flask

app = Flask(__name__)

@app.route('/')
def home():
    return 'Hello from containerized Python!'

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=5000)

# requirements.txt
flask==3.0.0

Step 2: Write the Dockerfile

# Dockerfile
FROM python:3.11-slim

WORKDIR /app

# Copy only requirements first to leverage Docker caching
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copy the rest of the application
COPY app.py .

EXPOSE 5000

CMD ["python", "app.py"]

Pro tip: Copy requirements.txt separately and run pip install before copying your code. This way, Docker can cache the dependency layer, so rebuilds are blazing fast when you only change app code.

Step 3: Build and test locally

docker build -t flask-hello .
docker run -d -p 5000:5000 --name test-app flask-hello
curl http://localhost:5000
# Output: Hello from containerized Python!

# Clean up if needed
docker stop test-app && docker rm test-app

Step 4: Create an ECR repository

aws ecr create-repository --repository-name flask-hello --region us-east-1
# Output includes the repositoryUri, e.g., 123456789012.dkr.ecr.us-east-1.amazonaws.com/flask-hello

Step 5: Authenticate and push

# Authenticate Docker to your ECR registry
aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin 123456789012.dkr.ecr.us-east-1.amazonaws.com

# Tag your image with the ECR repository URI
 docker tag flask-hello:latest 123456789012.dkr.ecr.us-east-1.amazonaws.com/flask-hello:latest

# Push to ECR
docker push 123456789012.dkr.ecr.us-east-1.amazonaws.com/flask-hello:latest

If you run docker images, you'll see your locally tagged image. The push output shows compressed layer uploads — that's ECR storing your image in AWS.

Step 6: Verify by pulling and running

# Optionally test from a separate machine
docker pull 123456789012.dkr.ecr.us-east-1.amazonaws.com/flask-hello:latest
docker run -d -p 5000:5000 flask-hello

You've now containerized a Python app with Docker on ECR — a production-ready artifact that can be deployed to ECS, EKS, or EC2 with zero environment surprises.

Compare options / when to choose what

There are several ways to containerize and store a Python app. Here's how Docker+ECR stacks up:

Choose ECR when you're all-in on AWS. Choose Docker Hub if you want a quick public demo. Use a VM if you're migrating a legacy monolith that can't be containerized.

Troubleshooting & edge cases

Here are common issues you'll hit:

• denied: Your Authorization Token has expired: Re-run aws ecr get-login-password — tokens expire after 12 hours.
• no space left on device during build: Docker cache and old images accumulate. Run docker system prune to clean up.
• Port already in use (failure on docker run -p 5000:5000): Change the host port, e.g., -p 5001:5000.
• exec: "python": executable file not found: Your Dockerfile's CMD uses a Python that isn't in the image base. Double-check your FROM base (e.g., python:3.11-slim includes python).
• ECR push fails with retrying in X seconds: Network issue or large image. Check your internet connection and consider using a smaller base image.
• Image size too large: Switch to python:3.11-slim or alpine variants, and use --no-cache-dir in pip.

What you learned & what's next

You now understand the core concept of containerize a Python app with Docker on ECR, from authoring a Dockerfile to pushing a versioned image to AWS. You applied the process hands-on with Flask, and you know how to troubleshoot common Docker and ECR errors.

This skill is the backbone of deploying Python services on AWS. The natural next step is learning to run your containerized app on Amazon ECS (Elastic Container Service) or EKS (Kubernetes) — that's where your image truly goes to work with auto-scaling and load balancing. You're ready to move from packaging to orchestration.