Docker Spaces Advanced

Docker Spaces give you complete control over your application's environment. Use any programming language, framework, or system dependency by providing a custom Dockerfile. This is ideal for complex applications that go beyond what Gradio or Streamlit SDKs offer.

Setting Up a Docker Space

YAML (README.md)

---
title: My Docker App
emoji: 🐳
colorFrom: gray
colorTo: blue
sdk: docker
pinned: false
---

Writing a Dockerfile

Dockerfile

FROM python:3.11-slim

# Install system dependencies
RUN apt-get update && apt-get install -y \
    build-essential \
    libsndfile1 \
    ffmpeg \
    && rm -rf /var/lib/apt/lists/*

# Create a non-root user (required by Spaces)
RUN useradd -m -u 1000 user
USER user
ENV HOME=/home/user PATH=/home/user/.local/bin:$PATH

WORKDIR /home/user/app

# Install Python dependencies
COPY --chown=user requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copy application code
COPY --chown=user . .

# Expose port 7860 (required by Spaces)
EXPOSE 7860

# Run the application
CMD ["python", "app.py"]

Important: Docker Spaces must expose port 7860. Your application must listen on this port for Spaces to route traffic correctly. The container runs as a non-root user with UID 1000.

FastAPI Example

Python (app.py)

from fastapi import FastAPI
from fastapi.staticfiles import StaticFiles
import uvicorn

app = FastAPI()

@app.get("/api/health")
def health():
    return {"status": "healthy"}

@app.get("/api/predict")
def predict(text: str):
    # Your ML inference here
    return {"result": "prediction"}

app.mount("/", StaticFiles(directory="static", html=True), name="static")

if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=7860)

Persistent Storage

Attach persistent storage to your Docker Space for data that needs to survive container restarts:

Python

import os

# Persistent storage is mounted at /data
PERSISTENT_DIR = "/data"

# Store files that survive restarts
with open(os.path.join(PERSISTENT_DIR, "cache.json"), "w") as f:
    json.dump(data, f)

# Read persisted data
if os.path.exists(os.path.join(PERSISTENT_DIR, "cache.json")):
    with open(os.path.join(PERSISTENT_DIR, "cache.json")) as f:
        data = json.load(f)

GPU Docker Spaces

For GPU-accelerated Docker Spaces, use NVIDIA CUDA base images:

Dockerfile

FROM nvidia/cuda:12.1.0-cudnn8-runtime-ubuntu22.04

RUN apt-get update && apt-get install -y python3 python3-pip
RUN useradd -m -u 1000 user
USER user
ENV HOME=/home/user PATH=/home/user/.local/bin:$PATH

WORKDIR /home/user/app
COPY --chown=user requirements.txt .
RUN pip3 install --no-cache-dir -r requirements.txt
COPY --chown=user . .

EXPOSE 7860
CMD ["python3", "app.py"]

Build Optimization: Order your Dockerfile layers from least-frequently changed (base image, system deps) to most-frequently changed (application code). This maximizes Docker layer caching and speeds up rebuilds.

Docker Space Running!

You now have full control over your Space's environment. In the final lesson, learn best practices for optimizing and maintaining your Spaces.

Next: Best Practices →

← Streamlit Spaces Best Practices →

Ready to Go Deeper?

Live instructor-led courses from our partners. Affiliate disclosure.

🧠

AI & ML Courses - 30% Off

Live instructor-led AI, machine learning, data science, and cloud courses for working professionals. Use code Limited30 at checkout.

Edureka

📊

DataCamp - AI & Data Science

Hands-on Python, machine learning, and AI courses with interactive exercises and real projects.

DataCamp

🎓

edX - Top AI Courses

University-level AI courses from MIT, Harvard, Stanford. Earn certificates that employers recognize.

edX