Skip to main content
This quickstart will walk you through creating a simple image classification model using Cog. You’ll learn how to define a model, run predictions, build a Docker image, and serve predictions via HTTP.

​
Prerequisites

Before you begin, make sure you have:
  • Cog installed - See the installation guide if you haven’t installed Cog yet
  • Docker running - Cog uses Docker to create containers for your model

​
Create a project

First, let’s create a new directory for your Cog project: 
mkdir cog-quickstart
cd cog-quickstart

​
Define your model

1

Create cog.yaml

Create a file called cog.yaml that defines your model’s environment:
cog.yaml
build:
  python_version: "3.12"
  python_requirements: requirements.txt
predict: "predict.py:Predictor"
If you have a machine with an NVIDIA GPU, add gpu: true to the build section to enable GPU acceleration.
2

Create requirements.txt

Create a requirements.txt file with your Python dependencies:
requirements.txt
pillow==11.1.0
torch==2.6.0
torchvision==0.21.0
3

Create predict.py

Create a predict.py file that defines how predictions are run:
predict.py
import os
os.environ["TORCH_HOME"] = "."

import torch
from cog import BasePredictor, Input, Path
from PIL import Image
from torchvision import models

WEIGHTS = models.ResNet50_Weights.IMAGENET1K_V1

class Predictor(BasePredictor):
    def setup(self):
        """Load the model into memory to make running multiple predictions efficient"""
        self.device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
        self.model = models.resnet50(weights=WEIGHTS).to(self.device)
        self.model.eval()

    def predict(self, image: Path = Input(description="Image to classify")) -> dict:
        """Run a single prediction on the model"""
        img = Image.open(image).convert("RGB")
        preds = self.model(WEIGHTS.transforms()(img).unsqueeze(0).to(self.device))
        top3 = preds[0].softmax(0).topk(3)
        categories = WEIGHTS.meta["categories"]
        return {categories[i]: p.detach().item() for p, i in zip(*top3)}
This example creates a ResNet-50 image classifier that:
  • Loads the model in setup() (called once when the container starts)
  • Takes an image as input via the predict() method
  • Returns the top 3 predicted categories with confidence scores

​
Run a prediction

Now let’s test the model by running a prediction: 
# Download a test image
curl https://gist.githubusercontent.com/bfirsh/3c2115692682ae260932a67d93fd94a8/raw/56b19f53f7643bb6c0b822c410c366c3a6244de2/mystery.jpg > input.jpg

# Run a prediction
cog predict -i [email protected]
The first time you run cog predict, it will build a Docker container with all your dependencies. This may take a few minutes. Subsequent predictions will be much faster.
You should see output like this: 
{
  "tiger_cat": 0.4874822497367859,
  "tabby": 0.23169134557247162,
  "Egyptian_cat": 0.09728282690048218
}

​
Build a Docker image

You can build your model into a standalone Docker image that serves predictions via HTTP: 
cog build -t my-classifier
This creates a Docker image called my-classifier:latest that includes:
  • Your model code
  • All dependencies
  • An HTTP server for serving predictions

​
Serve predictions via HTTP

Run the Docker image to start an HTTP server: 
docker run -d -p 5000:5000 my-classifier
Now you can send predictions via HTTP: 
curl http://localhost:5000/predictions -X POST \
  -H 'Content-Type: application/json' \
  -d '{"input": {"image": "https://gist.githubusercontent.com/bfirsh/3c2115692682ae260932a67d93fd94a8/raw/56b19f53f7643bb6c0b822c410c366c3a6244de2/mystery.jpg"}}'
You can also use cog serve to build and serve in one command during development.

​
Push to a registry

To deploy your model, you can push it to a Docker registry. First, add the image name to your cog.yaml:
cog.yaml
image: "r8.im/your-username/my-classifier"
build:
  python_version: "3.12"
  python_requirements: requirements.txt
predict: "predict.py:Predictor"
Then push it: 
cog push
The Docker image is now accessible to anyone with access to the registry and can be deployed to any infrastructure that runs Docker.

​
Next steps

Set up your own model

Learn how to adapt Cog for your own machine learning model

Deploy your model

Deploy your Cog model to production

YAML reference

Explore all configuration options in cog.yaml

Python API

Learn about the Predictor interface in detail

Build docs developers (and LLMs) love

Get started for freeTalk to us