Ship a Scikit-Learn Model With FastAPI, Docker, CI/CD

If you want to deploy sklearn model FastAPI workflows reliably, the model file is only one part of the system. A useful production-style setup also needs a clear project structure, safe artifact loading, request validation, Docker packaging, repeatable tests, and a simple CI/CD path that can build, verify, and ship the service.

This tutorial turns a trained Scikit-Learn classifier into a FastAPI prediction API, packages it with Docker, and adds a lightweight deployment workflow. The implementation is grounded in the researched examples: a breast cancer classifier saved with joblib, FastAPI endpoints for /health and /predict, Docker images built with uvicorn, and a deployment path that can push an image to Docker Hub or another container registry.

1. Project Architecture for a Production ML API

A good architecture separates training code, application code, model artifacts, tests, and deployment files. The MachineLearningMastery example uses a simple structure with app/, artifacts/, train.py, and dependency files. The PythonGuides example expands that idea by separating schemas, model-loading logic, tests, Docker files, and saved model assets.

For this tutorial, use a compact structure that keeps the model serving code clean while remaining easy to run locally:

sklearn-fastapi-app/
├── app/
│   ├── __init__.py
│   ├── main.py              # FastAPI application
│   └── schemas.py           # Pydantic request/response models
├── artifacts/
│   └── breast_cancer_model.joblib
├── tests/
│   └── test_api.py
├── train.py                 # Training and artifact export
├── requirements.txt
├── Dockerfile
├── .dockerignore
└── ci_cd.sh                 # Simple local/CI deployment script

Create the directories:

mkdir sklearn-fastapi-app
cd sklearn-fastapi-app
mkdir app artifacts tests
touch app/__init__.py

Use the core dependencies shown across the researched tutorials: fastapi, uvicorn, scikit-learn, joblib, numpy, and pydantic. The MachineLearningMastery example uses fastapi[standard], scikit-learn, joblib, and numpy; the Docker examples also include uvicorn.

fastapi[standard]
uvicorn
scikit-learn
joblib
numpy
pydantic

Install them:

pip install -r requirements.txt

Recommended file responsibilities

A production ML API is not just “a model behind an endpoint.” The sources consistently show the same pattern: save the model, load it in FastAPI, validate input with Pydantic, expose a prediction route, then package the service with Docker.

2. Saving and Loading a Scikit-Learn Model Safely

The first step is to train a model and save everything needed for inference. The MachineLearningMastery tutorial uses the built-in breast cancer dataset, trains a RandomForestClassifier with 200 estimators, evaluates accuracy, and stores a dictionary containing the model, target names, and feature names in artifacts/breast_cancer_model.joblib.

Create train.py:

from pathlib import Path

import joblib
from sklearn.datasets import load_breast_cancer
from sklearn.ensemble import RandomForestClassifier
from sklearn.metrics import accuracy_score
from sklearn.model_selection import train_test_split


def main():
    data = load_breast_cancer()
    X = data.data
    y = data.target

    X_train, X_test, y_train, y_test = train_test_split(
        X,
        y,
        test_size=0.2,
        random_state=42,
        stratify=y,
    )

    model = RandomForestClassifier(
        n_estimators=200,
        random_state=42,
    )

    model.fit(X_train, y_train)

    predictions = model.predict(X_test)
    accuracy = accuracy_score(y_test, predictions)

    artifact = {
        "model": model,
        "target_names": data.target_names.tolist(),
        "feature_names": data.feature_names.tolist(),
    }

    output_path = Path("artifacts/breast_cancer_model.joblib")
    output_path.parent.mkdir(parents=True, exist_ok=True)

    joblib.dump(artifact, output_path)

    print(f"Model saved to: {output_path}")
    print(f"Test accuracy: {accuracy:.4f}")


if __name__ == "__main__":
    main()

Run it:

python train.py

The researched output from this setup is:

Model saved to: artifacts/breast_cancer_model.joblib
Test accuracy: 0.9561

That 0.9561 value is the test accuracy reported by the source example for this breast cancer classifier. Do not treat it as a universal benchmark; it is specific to that dataset, split, model configuration, and example.

Joblib vs pickle in the researched examples

The sources show both joblib and pickle for saving Scikit-Learn artifacts. The FastAPI + Docker examples use joblib.dump() / joblib.load() in several places, while another FastAPI tutorial demonstrates pickle.

Critical warning: if you use pickle, do not deserialize files from untrusted sources. The researched FastAPI tutorial explicitly notes that unpickling can execute malicious code.

For this tutorial, the API loads a joblib artifact from a known local path created by train.py.

3. Building a FastAPI Prediction Endpoint

Now you can expose the trained model through FastAPI. The MachineLearningMastery example loads the model during FastAPI startup, stores it on app.state, provides a /health endpoint, and exposes a /predict route that returns both a predicted class and probabilities.

First, define request and response schemas in app/schemas.py.

from pydantic import BaseModel


class PredictionRequest(BaseModel):
    mean_radius: float
    mean_texture: float
    mean_perimeter: float
    mean_area: float
    mean_smoothness: float
    mean_compactness: float
    mean_concavity: float
    mean_concave_points: float
    mean_symmetry: float
    mean_fractal_dimension: float
    radius_error: float
    texture_error: float
    perimeter_error: float
    area_error: float
    smoothness_error: float
    compactness_error: float
    concavity_error: float
    concave_points_error: float
    symmetry_error: float
    fractal_dimension_error: float
    worst_radius: float
    worst_texture: float
    worst_perimeter: float
    worst_area: float
    worst_smoothness: float
    worst_compactness: float
    worst_concavity: float
    worst_concave_points: float
    worst_symmetry: float
    worst_fractal_dimension: float


class PredictionResponse(BaseModel):
    prediction_id: int
    prediction_label: str
    probabilities: dict[str, float]


class HealthResponse(BaseModel):
    status: str

Now create app/main.py:

from pathlib import Path

import joblib
import numpy as np
from fastapi import FastAPI, HTTPException

from app.schemas import HealthResponse, PredictionRequest, PredictionResponse


ARTIFACT_PATH = Path("artifacts/breast_cancer_model.joblib")

app = FastAPI(
    title="Breast Cancer Prediction API",
    version="1.0.0",
    description="A FastAPI server for serving a scikit-learn breast cancer classifier",
)


@app.on_event("startup")
def load_model():
    if not ARTIFACT_PATH.exists():
        raise RuntimeError(
            f"Model file not found at {ARTIFACT_PATH}. Run `python train.py` first."
        )

    artifact = joblib.load(ARTIFACT_PATH)

    app.state.model = artifact["model"]
    app.state.target_names = artifact["target_names"]
    app.state.feature_names = artifact["feature_names"]


@app.get("/health", response_model=HealthResponse)
def health():
    return {"status": "ok"}


@app.post("/predict", response_model=PredictionResponse)
def predict(request: PredictionRequest):
    try:
        features = np.array([[
            request.mean_radius,
            request.mean_texture,
            request.mean_perimeter,
            request.mean_area,
            request.mean_smoothness,
            request.mean_compactness,
            request.mean_concavity,
            request.mean_concave_points,
            request.mean_symmetry,
            request.mean_fractal_dimension,
            request.radius_error,
            request.texture_error,
            request.perimeter_error,
            request.area_error,
            request.smoothness_error,
            request.compactness_error,
            request.concavity_error,
            request.concave_points_error,
            request.symmetry_error,
            request.fractal_dimension_error,
            request.worst_radius,
            request.worst_texture,
            request.worst_perimeter,
            request.worst_area,
            request.worst_smoothness,
            request.worst_compactness,
            request.worst_concavity,
            request.worst_concave_points,
            request.worst_symmetry,
            request.worst_fractal_dimension,
        ]])

        model = app.state.model
        target_names = app.state.target_names

        prediction_id = int(model.predict(features)[0])
        probabilities = model.predict_proba(features)[0]

        return {
            "prediction_id": prediction_id,
            "prediction_label": target_names[prediction_id],
            "probabilities": {
                target_names[i]: float(round(probabilities[i], 6))
                for i in range(len(target_names))
            },
        }

    except Exception as exc:
        raise HTTPException(status_code=500, detail=str(exc))

Run the server locally:

uvicorn app.main:app --host 0.0.0.0 --port 8000

Then open:

http://localhost:8000/docs

The researched FastAPI examples highlight that FastAPI automatically generates interactive API documentation. The Auroria example specifically points to /docs and /redoc, while another FastAPI example notes that Swagger UI shows endpoints, arguments, possible errors, and curl commands.

To deploy sklearn model FastAPI services cleanly, this generated documentation is useful because consumers can inspect the request schema before sending prediction traffic.

4. Adding Input Validation and Error Handling

Pydantic validation is one of the most important FastAPI features for ML APIs. In the researched examples, Pydantic models define the request shape, such as DataPoint, DataPointDTO, IrisInput, and more detailed customer feature schemas.

If a request does not match the schema, FastAPI/Pydantic can reject it before the model sees malformed input. One source notes that invalid JSON for a Pydantic schema returns 422 Unprocessable Entity.

Validation approaches shown in the sources

The breast cancer example uses named fields because the dataset has 30 named features. That makes the request verbose, but it avoids ambiguity about feature order.

Add explicit validation where the source supports it

The PythonGuides example uses Pydantic Field constraints such as:

monthly_active_days: int = Field(..., ge=0, le=31)
monthly_spend_usd: float = Field(..., gt=0)
onboarding_completed: Literal[0, 1]

For the breast cancer dataset, the source data does not provide medically meaningful min/max constraints for each feature. So this tutorial keeps the fields as float rather than inventing thresholds.

Do not add fake validation ranges just to look “production ready.” If your training data or domain rules do not define valid bounds, keep validation focused on type, shape, and required fields until you can justify stricter constraints.

Error handling used here

The API handles three common cases:

• Missing model artifact: startup fails with a clear message telling the operator to run python train.py.
• Invalid request shape: FastAPI/Pydantic rejects the request before inference.
• Unexpected prediction error: the endpoint returns an HTTP 500 with error details.

This mirrors the researched examples where missing model files are checked, request data is validated, and prediction failures return structured error output.

5. Containerizing the Model API With Docker

Docker packages the app, model artifact, and dependencies into one image. The researched Docker tutorials use slim Python base images, copy requirements.txt, install dependencies, copy the model and app files, then start FastAPI with Uvicorn.

Create a .dockerignore file so local cache files do not get copied into the image:

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

Create Dockerfile:

FROM python:3.10-slim

WORKDIR /app

COPY requirements.txt .

RUN pip install --no-cache-dir -r requirements.txt

COPY app/ app/
COPY artifacts/ artifacts/

EXPOSE 8000

CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

This follows the same pattern shown in the researched Docker examples:

Build the image:

docker build -t sklearn-fastapi-api:latest .

Run the container:

docker run -p 8000:8000 sklearn-fastapi-api:latest

Check the health endpoint:

curl http://localhost:8000/health

Expected response:

{"status":"ok"}

The Substack Docker example highlights a common accessibility issue: make sure --host 0.0.0.0 is set and that port mapping is correct. In this tutorial, docker run -p 8000:8000 maps local port 8000 to container port 8000.

6. Writing Basic Tests for Predictions and API Health

The sources mention local testing, a health check endpoint, test_api.py, Swagger UI, curl requests, and Docker verification. For a simple test layer, check two things:

1. The API starts and /health returns {"status": "ok"}.
2. The /predict endpoint returns the expected response keys for a valid request.

Create tests/test_api.py:

from fastapi.testclient import TestClient

from app.main import app


VALID_PAYLOAD = {
    "mean_radius": 1.0,
    "mean_texture": 1.0,
    "mean_perimeter": 1.0,
    "mean_area": 1.0,
    "mean_smoothness": 1.0,
    "mean_compactness": 1.0,
    "mean_concavity": 1.0,
    "mean_concave_points": 1.0,
    "mean_symmetry": 1.0,
    "mean_fractal_dimension": 1.0,
    "radius_error": 1.0,
    "texture_error": 1.0,
    "perimeter_error": 1.0,
    "area_error": 1.0,
    "smoothness_error": 1.0,
    "compactness_error": 1.0,
    "concavity_error": 1.0,
    "concave_points_error": 1.0,
    "symmetry_error": 1.0,
    "fractal_dimension_error": 1.0,
    "worst_radius": 1.0,
    "worst_texture": 1.0,
    "worst_perimeter": 1.0,
    "worst_area": 1.0,
    "worst_smoothness": 1.0,
    "worst_compactness": 1.0,
    "worst_concavity": 1.0,
    "worst_concave_points": 1.0,
    "worst_symmetry": 1.0,
    "worst_fractal_dimension": 1.0,
}


def test_health():
    with TestClient(app) as client:
        response = client.get("/health")

    assert response.status_code == 200
    assert response.json() == {"status": "ok"}


def test_predict_returns_prediction_fields():
    with TestClient(app) as client:
        response = client.post("/predict", json=VALID_PAYLOAD)

    assert response.status_code == 200

    data = response.json()

    assert "prediction_id" in data
    assert "prediction_label" in data
    assert "probabilities" in data
    assert isinstance(data["probabilities"], dict)


def test_predict_rejects_missing_fields():
    with TestClient(app) as client:
        response = client.post("/predict", json={"mean_radius": 1.0})

    assert response.status_code == 422

Run the tests as a plain Python script only if you add a small runner, or execute them with your normal test runner if your environment already has one. At minimum, the test file documents the expected behavior and can be used in a CI step.

You can also verify the Dockerized API using curl, as shown in the researched Docker example:

curl -X POST "http://localhost:8000/predict" \
  -H "Content-Type: application/json" \
  -d '{
    "mean_radius": 1.0,
    "mean_texture": 1.0,
    "mean_perimeter": 1.0,
    "mean_area": 1.0,
    "mean_smoothness": 1.0,
    "mean_compactness": 1.0,
    "mean_concavity": 1.0,
    "mean_concave_points": 1.0,
    "mean_symmetry": 1.0,
    "mean_fractal_dimension": 1.0,
    "radius_error": 1.0,
    "texture_error": 1.0,
    "perimeter_error": 1.0,
    "area_error": 1.0,
    "smoothness_error": 1.0,
    "compactness_error": 1.0,
    "concavity_error": 1.0,
    "concave_points_error": 1.0,
    "symmetry_error": 1.0,
    "fractal_dimension_error": 1.0,
    "worst_radius": 1.0,
    "worst_texture": 1.0,
    "worst_perimeter": 1.0,
    "worst_area": 1.0,
    "worst_smoothness": 1.0,
    "worst_compactness": 1.0,
    "worst_concavity": 1.0,
    "worst_concave_points": 1.0,
    "worst_symmetry": 1.0,
    "worst_fractal_dimension": 1.0
  }'

When you deploy sklearn model FastAPI applications, these basic checks catch the most common failures: missing artifacts, broken startup loading, invalid schemas, and container networking mistakes.

7. Setting Up a Simple CI/CD Deployment Flow

The researched sources do not provide a vendor-specific CI/CD configuration. They do, however, show the core deployment actions:

• Install dependencies with pip install -r requirements.txt.
• Train or generate the model artifact with python train.py.
• Build a Docker image with docker build.
• Run the container locally with docker run.
• Test an endpoint with curl.
• Push the image to Docker Hub or another container registry.
• Deploy to a target platform such as a server, cloud platform, or FastAPI Cloud where applicable.

A simple CI/CD flow can wrap those steps into one script. Create ci_cd.sh:

#!/usr/bin/env bash
set -e

IMAGE_NAME="sklearn-fastapi-api"
IMAGE_TAG="${1:-latest}"

echo "Installing dependencies..."
pip install -r requirements.txt

echo "Training model..."
python train.py

echo "Building Docker image..."
docker build -t "${IMAGE_NAME}:${IMAGE_TAG}" .

echo "Running container for smoke test..."
docker rm -f sklearn-fastapi-smoke-test || true
docker run -d --name sklearn-fastapi-smoke-test -p 8000:8000 "${IMAGE_NAME}:${IMAGE_TAG}"

echo "Waiting briefly for API startup..."
sleep 5

echo "Checking health endpoint..."
curl --fail http://localhost:8000/health

echo "Stopping smoke test container..."
docker rm -f sklearn-fastapi-smoke-test

echo "CI/CD flow completed successfully."

Make it executable:

chmod +x ci_cd.sh

Run it:

./ci_cd.sh latest

Optional registry push

The Auroria example shows tagging and pushing an image:

docker build --tag my-name/my-sklearn-api-service:latest .
docker push my-name/my-sklearn-api-service:latest

Using the same pattern, you can tag your image for a registry:

docker tag sklearn-fastapi-api:latest my-name/sklearn-fastapi-api:latest
docker push my-name/sklearn-fastapi-api:latest

At the time of writing, the researched material mentions Docker Hub, private container registries, cloud servers, and FastAPI Cloud, but it does not provide a universal one-command deployment recipe for every platform. The portable part is the container image: once built and pushed, the same image can be run by infrastructure that supports Docker containers.

Minimal CI/CD stages

This is enough to deploy sklearn model FastAPI services in a repeatable way without locking the tutorial to one CI provider.

8. Common Deployment Mistakes and How to Avoid Them

Even small ML APIs fail in predictable ways. The researched tutorials call out several common problems around missing model files, input shape mismatches, port mapping, dependency conflicts, and unsafe deserialization.

1. Loading the model on every request

One FastAPI tutorial notes that loading the model on each request can be useful if you want to swap the model while the server is running, but it may not be ideal when the model is large or changes infrequently. The MachineLearningMastery and Auroria examples load the model once during application startup.

For this tutorial, loading once at startup is the cleaner default.

2. Forgetting to copy the model into the Docker image

The Substack Docker example lists “container can’t find the model file” as a common issue. The fix is to ensure the model file is copied into the image.

In this tutorial:

COPY artifacts/ artifacts/

If you build the image before running python train.py, the artifacts/ directory may not contain the model file. Train first, then build.

3. Binding Uvicorn to the wrong host

Inside Docker, binding to localhost can make the API unreachable from outside the container. The Docker examples use:

--host 0.0.0.0

This tutorial’s Dockerfile includes:

CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

Also confirm your port mapping:

docker run -p 8000:8000 sklearn-fastapi-api:latest

4. Sending the wrong feature shape

The synthetic SVM example checks that the input list has exactly 4 elements. The breast cancer model expects 30 features. If you use named Pydantic fields, FastAPI will reject missing fields with a 422 response.

This is why schema design matters. A loosely defined list is shorter, but named fields produce better API documentation and fewer ordering mistakes.

5. Saving preprocessing separately and forgetting it at inference

The PythonGuides churn example saves a model, scaler, and feature names separately:

model/churn_model.pkl
model/scaler.pkl
model/feature_names.pkl

That example also fits the scaler only on the training data and applies it during inference. If your model depends on preprocessing, save and load the preprocessing artifact too. The breast cancer example used here saves only the model, target names, and feature names because that is what the source example provides.

6. Using unsafe or untrusted serialized files

The pickle-based FastAPI source explicitly warns that pickle is not secure for untrusted data. If your workflow uses serialized model files, treat them as trusted build artifacts, not as user uploads.

7. Shipping an untested container

The Auroria example verifies the built container by running it and calling the prediction endpoint with curl. The Substack example tests /, /docs, and /predict.

Before deployment, always perform at least:

• Health check: GET /health
• Prediction smoke test: POST /predict
• Documentation check: /docs
• Docker run check: docker run -p ...

Bottom Line

To deploy sklearn model FastAPI services effectively, use a repeatable structure: train the model, save the artifact, load it once at FastAPI startup, validate requests with Pydantic, expose /health and /predict, package everything with Docker, and test the container before pushing it to a registry.

The researched examples consistently support this path. FastAPI provides automatic interactive documentation at /docs, Pydantic handles schema validation and can return 422 errors for invalid input, joblib is widely used for Scikit-Learn artifacts, and Docker helps avoid dependency and environment mismatches across laptops, servers, and cloud platforms.

If you only remember one workflow, use this:

python train.py
uvicorn app.main:app --host 0.0.0.0 --port 8000
docker build -t sklearn-fastapi-api:latest .
docker run -p 8000:8000 sklearn-fastapi-api:latest
curl http://localhost:8000/health

That gives you the core loop for training, serving, packaging, and verifying a Scikit-Learn FastAPI deployment.

FAQ