New to containers? Start with Container Image Fundamentals to understand the basics before diving into this guide.

Building Python Applications with CleanStart

CleanStart provides hardened Python base images (cleanstart/python) with pre-scanned OS dependencies (zero CVEs), Python 3.11, 3.12, 3.13 variants, multi-stage build support, FIPS 140-3 mode available, and optimization for Cloud Native deployments.

The following diagram illustrates the Python application deployment workflow with CleanStart:

graph LR    A["Python Source<br/>app.py<br/>requirements.txt"] -->|Build Stage| B["cleanstart/python:3.12<br/>Builder"]     B -->|Install| C["pip install<br/>requirements.txt"]    B -->|Dependencies| D["Flask 3.0.0<br/>gunicorn 21.2.0<br/>Transitive deps"]     C -->|Cache| E["Wheel files<br/>Pre-compiled<br/>Packages"]     E -->|Copy Only| F["Production Stage<br/>cleanstart/python:3.12"]     F -->|Setup| G["Create App User<br/>Non-root"]     G -->|Security| H["No build tools<br/>Read-only FS<br/>Port 5000"]     H -->|Entrypoint| I["gunicorn app:app"]     I -->|Deploy| J["Container Registry<br/>registry.cleanstart.com"]     J -->|Push with| K["SBOM<br/>Cosign Signature<br/>Provenance"]     K -->|Runtime| L["Kubernetes Pod<br/>or Docker"]     L -->|Port| M["Port 5000<br/>JSON Responses"]     M -->|Request| N["curl localhost:5000"]     N -->|Response| O["Hello from CleanStart<br/>JSON Output"]     style A fill:#ccffcc    style B fill:#99ccff    style C fill:#99ccff    style F fill:#99ff99    style I fill:#ffff99    style O fill:#99ff99

Quick Start: A Simple Flask Application

Step 1: Create Your Project

mkdir my-python-appcd my-python-app

Create app.py:

from flask import Flaskimport logging app = Flask(__name__)logging.basicConfig(level=logging.INFO) @app.route('/')def hello():    logging.info('Request received')    return {'message': 'Hello from CleanStart', 'version': '1.0'} if __name__ == '__main__':    app.run(host='0.0.0.0', port=5000, debug=False)

Create requirements.txt:

Flask==3.0.0gunicorn==21.2.0

Step 2: Create a Production Dockerfile

# Build stageFROM cleanstart/python:3.12 AS builder WORKDIR /appRUN pip install --upgrade pip setuptools wheelCOPY requirements.txt .RUN pip install --no-cache-dir -r requirements.txt # Production stageFROM cleanstart/python:3.12 WORKDIR /app # Create app userRUN useradd -m -u 1000 appuser # Copy dependencies from builderCOPY --from=builder /usr/local/lib/python3.12/site-packages /usr/local/lib/python3.12/site-packagesCOPY --from=builder /usr/local/bin /usr/local/bin COPY --chown=appuser:appuser app.py . USER appuserEXPOSE 5000 HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \    CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:5000').read()" || exit 1 CMD ["gunicorn", "--bind", "0.0.0.0:5000", "--workers", "4", "--timeout", "60", "app:app"]

Step 3: Build and Run Locally

# Build the imagedocker build -t my-python-app:latest . # Run the containerdocker run --rm -p 5000:5000 my-python-app:latest # Test the applicationcurl http://localhost:5000

Multi-Stage Builds: The Complete Pattern

Multi-stage builds reduce final image size by excluding build tools:

# Stage 1: DependenciesFROM cleanstart/python:3.12 AS dependencies WORKDIR /tmpCOPY requirements.txt . RUN pip install --user --no-cache-dir \    -r requirements.txt # Stage 2: Source buildFROM cleanstart/python:3.12 AS builder WORKDIR /buildCOPY . . # Stage 3: RuntimeFROM cleanstart/python:3.12 WORKDIR /app RUN useradd -m -u 1000 appuser && \    chown -R appuser:appuser /app # Copy Python packages from dependencies stageCOPY --from=dependencies /root/.local /home/appuser/.local # Copy application code from builder stageCOPY --from=builder --chown=appuser:appuser /build . ENV PATH=/home/appuser/.local/bin:$PATHUSER appuser EXPOSE 8000HEALTHCHECK --interval=30s --timeout=3s CMD python -c "import requests; requests.get('http://localhost:8000/health')" || exit 1 CMD ["python", "-m", "uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8000"]

Testing Your Application

Add pytest to development requirements:

pip install pytest pytest-cov

Create test_app.py:

import pytestfrom app import app @pytest.fixturedef client():    app.config['TESTING'] = True    with app.test_client() as client:        yield client def test_hello(client):    response = client.get('/')    assert response.status_code == 200    assert response.json['message'] == 'Hello from CleanStart'

Run tests in the Docker container:

FROM cleanstart/python:3.12 AS test WORKDIR /appCOPY requirements.txt .RUN pip install --no-cache-dir -r requirements.txt pytest COPY . .RUN pytest --cov=. --cov-report=term-missing

Production Deployment Considerations

Environment Variables

Externalize configuration using environment variables:

import osfrom dotenv import load_dotenv load_dotenv() LOG_LEVEL = os.getenv('LOG_LEVEL', 'INFO')DATABASE_URL = os.getenv('DATABASE_URL', 'sqlite:///app.db')SECRET_KEY = os.getenv('SECRET_KEY', 'dev-key-change-in-production')

Run with secrets:

docker run \    -e LOG_LEVEL=INFO \    -e DATABASE_URL='postgresql://user:pass@db:5432/myapp' \    -e SECRET_KEY='production-secret-key' \    my-python-app:latest

Logging to Stdout

For container orchestration (Kubernetes, Cloud Run), send logs to stdout:

import loggingimport sys # Configure logging to stdoutlogging.basicConfig(    level=logging.INFO,    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',    stream=sys.stdout,    handlers=[logging.StreamHandler(sys.stdout)]) logger = logging.getLogger(__name__)

Health Checks

Implement health check endpoints for orchestrators:

@app.route('/health')def health():    return {'status': 'healthy', 'version': '1.0'}, 200 @app.route('/ready')def readiness():    # Check database connectivity, external services, etc.    try:        # db.ping()        return {'ready': True}, 200    except Exception as e:        logger.error(f'Readiness check failed: {e}')        return {'ready': False, 'error': str(e)}, 503

Securing Your Python Application

User Isolation

Always run as non-root:

RUN useradd -m -u 1000 appuserUSER appuser

Minimal Dependencies

Keep your requirements.txt lean:

# Audit dependencies for vulnerabilitiespip install pip-auditpip-audit

Security Headers (for web apps)

@app.after_requestdef set_security_headers(response):    response.headers['X-Content-Type-Options'] = 'nosniff'    response.headers['X-Frame-Options'] = 'DENY'    response.headers['Strict-Transport-Security'] = 'max-age=31536000'    return response

Performance Optimization

Gunicorn Workers

Calculate optimal worker count:

workers = (2 × CPUs) + 1

For a 4-CPU container: --workers 9

CMD ["gunicorn", "--workers", "9", "--worker-class", "sync", \     "--bind", "0.0.0.0:8000", "--timeout", "120", \     "--access-logfile", "-", "--error-logfile", "-", "app:app"]

Uvicorn (for async)

For high-concurrency workloads:

CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8000", \     "--workers", "4", "--loop", "uvloop"]

Deploying to Cloud Run (Google Cloud)

# Build and pushgcloud builds submit --tag gcr.io/my-project/my-python-app # Deploygcloud run deploy my-python-app \    --image gcr.io/my-project/my-python-app:latest \    --platform managed \    --region us-central1 \    --allow-unauthenticated \    --memory 512Mi \    --cpu 1 \    --timeout 60s \    --set-env-vars LOG_LEVEL=INFO,DATABASE_URL=...

Image Options

CleanStart provides Python variants:

Troubleshooting

Build Issues

Problem: Slow pip installs during Docker build Cause: Compiling packages from source in every layer rebuild; pip cache in read-only FS not persisting between layers Fix: Use --no-cache-dir flag and pre-download wheels in builder stage. Consider using --pre-built-wheels for faster installations. Also copy requirements.txt before application code for layer caching.

Problem: ModuleNotFoundError: No module named 'xyz' at runtime Cause: PYTHONPATH not set correctly in CleanStart image; site-packages permissions issue with UID 65532; module not copied in multi-stage build Fix: Verify the site-packages path matches your Python version. In multi-stage builds, copy with explicit paths: COPY --from=builder /usr/local/lib/python3.12/site-packages /usr/local/lib/python3.12/site-packages. Check sys.path in running container with python -c "import sys; print(sys.path)". Ensure files are readable by your application user.

Problem: pip install fails with "Permission denied" or "Read-only file system" errors Cause: Read-only root filesystem enforcement; /tmp mounted as tmpfs that's too small; pip cache directory not writable Fix: In production with readOnlyRootFilesystem: true, pip must complete in build stage. If building at runtime, mount writable volumes: /tmp, /home/appuser/.cache, and /home/appuser/.local. For development in read-only mode, use emptyDir volumes in Kubernetes.

Problem: ERROR: Could not install packages due to an EnvironmentError Cause: Pip cache issues; incompatible Python version; corrupted wheels Fix: Add RUN pip cache purge before final stage. Explicitly pin Python version in Dockerfile. Test wheel compatibility: pip download --only-binary=:all: -r requirements.txt to verify pre-built wheels exist for your platform.

Problem: Build layer caching not working; every rebuild recompiles everything Cause: Requirements.txt copied together with application code; Docker detects source changes and rebuilds Fix: Structure Dockerfile with dependency layer first: COPY requirements.txt . && RUN pip install before COPY . .. This way, dependency layer caches when requirements unchanged.

Problem: __pycache__ directories bloating image size Cause: Bytecode cache not excluded in multi-stage copy Fix: Add .dockerignore file with __pycache__ and *.pyc entries. In Dockerfile, explicitly exclude: RUN find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true

Runtime Issues

Problem: ModuleNotFoundError or import errors in shell-less container (with cleanimg-init) Cause: Shell-less containers can't execute bash for debugging; Python path issues with CleanStart UID 65532 Note: CleanStart's default user is UID 65532. If your Dockerfile creates a custom user (e.g., UID 1000), adjust the troubleshooting commands accordingly. Fix: Add diagnostic endpoint to your Flask/FastAPI app to print sys.path and installed modules. Access via HTTP instead of shell. Log sys.path at startup: import sys; logger.info(f"Python path: {sys.path}"). Verify user has read permissions on site-packages.

Problem: Application crashes with permission errors after using cleanimg-init Cause: File ownership issues when copying with COPY --chown but container running as UID 65532; pip packages installed as root, not accessible to non-root user Fix: Use explicit chown in build: COPY --chown=65532:65532 for all files. For pip packages in multi-stage, copy to user-accessible directory: COPY --from=builder /home/appuser/.local /home/appuser/.local. Verify with docker run --rm my-app ls -la /usr/local/lib/python3.12/site-packages/ to check ownership.

Problem: Gunicorn workers crash with "Worker timeout" or hang during requests Cause: Workers set too high relative to CPU cores; timeout too aggressive for slow requests; single-threaded blocking operations Fix: Calculate workers as (2 * CPU) + 1. In containers, check actual CPU: docker run --cpus=1 my-app cat /proc/cpuinfo | grep processor | wc -l. Increase timeout: --timeout 120. For async operations, use uvicorn workers instead: --worker-class uvicorn.workers.UvicornWorker.

Problem: Uvicorn/Flask server doesn't bind to port, "Address already in use" Cause: Binding to localhost (127.0.0.1) instead of 0.0.0.0; port already in use from previous container; CleanStart network namespace issues Fix: Always bind to 0.0.0.0: app.run(host='0.0.0.0', port=5000). Verify exposure in Dockerfile: EXPOSE 5000. Check for orphaned processes: docker ps -a | grep exited. For CleanStart, ensure --net=host or proper port mapping: docker run -p 5000:5000.

Problem: HEALTHCHECK fails in shell-less container with cleanimg-init Cause: Health check command tries to use shell (sh) which doesn't exist; curl or wget not available; Python not in PATH Fix: Use Python directly without shell: HEALTHCHECK CMD python -c "import requests; requests.get('http://localhost:8000/health')". Alternatively, use a direct socket check instead of HTTP: HEALTHCHECK --interval=30s CMD python -c "import socket; socket.create_connection(('127.0.0.1', 8000), timeout=1)". Or implement TCP socket check without external tools.

Problem: Graceful shutdown not working with cleanimg-init as PID 1 Cause: Signals not properly forwarded to Python process; missing signal handlers in application Fix: Ensure your Python app explicitly handles SIGTERM: signal.signal(signal.SIGTERM, signal.SIGINT) or use Gunicorn which handles signals. With cleanimg-init, signals are forwarded to child process. Test with docker kill -s TERM container-id and verify app logs show shutdown message.

Problem: Out of Memory (OOM) killed; Python process consuming excess memory Cause: Memory leaks in application; unbounded caching; large data structures in request handlers; site-packages taking too much memory Fix: Increase container memory limit: docker run -m 1g my-app:latest. Monitor with docker stats. For production, set resource requests/limits in Kubernetes. If issue persists, profile with memory_profiler: install with pip install memory-profiler, decorate functions with @profile, and run python -m memory_profiler app.py. Consider using pympler for object tracking.

Problem: UID 65532 (non-root user in CleanStart) can't write to /tmp or application directories Cause: /tmp in read-only filesystem; files copied with wrong ownership; application tries to write to read-only locations Fix: Mount writable emptyDir volumes in Kubernetes for /tmp and application cache. In Dockerfile, ensure proper ownership with COPY --chown=65532:65532. Create writable directories: RUN mkdir -p /home/appuser/.cache && chown 65532:65532 /home/appuser/.cache. For read-only root, mount /tmp as tmpfs in pod spec.

Problem: ImportError or missing C extension modules Cause: Package compiled for different platform; system libraries missing; binary wheel not available for platform Fix: Ensure pure Python builds or pre-compiled wheels. Check package documentation for binary dependencies. For packages with C extensions (e.g., psycopg2), install build-essential in builder stage: RUN apt-get update && apt-get install -y build-essential python3-dev && pip install --no-cache-dir psycopg2-binary (note: prefer psycopg2-binary to avoid compilation).

Performance Issues

Problem: Application startup takes 30+ seconds Cause: Large site-packages being imported; lazy loading not used; many dependencies being loaded on startup Fix: Profile startup time: python -m cProfile -s cumulative app.py | head -20. Move imports into functions if not needed at startup. For Flask, use blueprint lazy registration. With Gunicorn, set --preload-app to load code once per worker. Consider gevent workers for reduced memory.

Problem: /tmp as tmpfs fills up during operation Cause: Temporary files not cleaned; cache accumulation; pip operations writing to /tmp Fix: Ensure application code cleans up tempfiles: use context managers with tempfile.NamedTemporaryFile() as f:. Monitor /tmp size: docker exec container df -h. For read-only root setup, mount larger tmpfs: emptyDir: {sizeLimit: "500Mi"} in Kubernetes.

Problem: venv vs system install causes path confusion Cause: Virtual environment in multi-stage build not copied correctly; PATH not set properly; Python finding system packages instead Fix: For pip --user installs in multi-stage, add to PATH: ENV PATH=/home/appuser/.local/bin:$PATH. For venv, copy entire venv directory and update shebang lines. Prefer pip install --user in CleanStart for simpler multi-stage (no need for venv activation).

CleanStart Production Hardening

Read-Only Root Filesystem

Enable immutable infrastructure by making the root filesystem read-only, with specific writable paths for your application:

apiVersion: v1kind: Podmetadata:  name: python-appspec:  containers:  - name: app    image: cleanstart/python:3.12    securityContext:      readOnlyRootFilesystem: true    volumeMounts:    - name: tmp      mountPath: /tmp    - name: app-cache      mountPath: /home/appuser/.cache    - name: pip-cache      mountPath: /home/appuser/.local  volumes:  - name: tmp    emptyDir: {}  - name: app-cache    emptyDir: {}  - name: pip-cache    emptyDir: {}

Shell-Less ENTRYPOINT

Remove shell from the container for reduced attack surface. Update your Dockerfile:

FROM cleanstart/python:3.12 WORKDIR /appCOPY requirements.txt .RUN pip install -r requirements.txt COPY . . # Declarative Image Builder: # Use cleanimg-init as PID 1ENTRYPOINT ["/cleanimg-init", "--"]CMD ["python", "-u", "app.py"]

cleanimg-customize: Custom Configuration

Inject production settings for Python applications:

FROM cleanstart/python:3.12 WORKDIR /appCOPY requirements.txt .RUN pip install -r requirements.txt COPY . . # Create and inject custom Python configurationRUN mkdir -p /etc/cleanimg && \    echo 'import warnings; warnings.filterwarnings("ignore")' > /app/warnings.conf ENTRYPOINT ["/cleanimg-init", "--"]CMD ["python", "-u", "-W", "ignore", "app.py"]

Security Context

Complete Kubernetes securityContext for hardened Python containers:

apiVersion: apps/v1kind: Deploymentmetadata:  name: python-appspec:  template:    spec:      securityContext:        fsGroup: 65532        seccompProfile:          type: RuntimeDefault      containers:      - name: app        image: cleanstart/python:3.12        securityContext:          allowPrivilegeEscalation: false          readOnlyRootFilesystem: true          runAsNonRoot: true          runAsUser: 65532          runAsGroup: 65532          capabilities:            drop:            - ALL        resources:          requests:            cpu: 100m            memory: 128Mi          limits:            cpu: 500m            memory: 512Mi

Next Steps

Read Advanced Python Deployment, Explore CleanStart Image Registry, and Join the Community Slack.