cog

library0.22.0pypypi✓ verified 25d ago

Cog is an open-source tool for packaging machine learning models into standard Docker containers. It allows you to define a Python `Predictor` class with `setup` and `predict` methods, which Cog then uses to build a Docker image for local testing or deployment to platforms like Replicate. The current version is 0.17.2, and it receives frequent minor updates with occasional major releases introducing significant architectural changes.

ai-ml devops

pip install cog

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · COG

cog

ai-mlpythonv0.22.0

Install

3.7s avg

Import

579ms

Disk

48MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.16.12 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.730s · 54MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 3.7s · import 0.428s · 40MB

48MB installed

● package 48MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

BasePredictor

✓ from cog import BasePredictor

Input

✓ from cog import Input

Path

✓ from cog import Path

Used for file inputs/outputs, typically `pathlib.Path` or `str` representations of paths.

replicate

✓ from cog import replicate

Used for programmatic interaction with the Replicate API, not for defining models.

Define a `Predictor` class inheriting from `BasePredictor`. Implement `setup()` to load your model and `predict()` to handle inference. `Input` specifies prediction inputs with types, descriptions, and defaults. `Path` is used for file-based inputs/outputs.

from cog import BasePredictor, Input, Path import torch class Predictor(BasePredictor): def setup(self): """Load the model into memory to make running multiple predictions efficient""" # Example: self.model = torch.load("./weights.pth") self.model = "a dummy model" def predict( self, text_input: str = Input(description="A text input"), scale: float = Input(description="Factor to scale by", default=1.5) ) -> str: """Run a single prediction on the model""" # Example: processed_input = self.preprocess(text_input) # output = self.model(processed_input, scale) output = f"Processed '{text_input}' with scale {scale}" return output # To run locally with Cog CLI: # 1. Create a cog.yaml file: `cog init` # 2. Add dependencies (e.g., torch) to requirements.txt # 3. Run prediction: `cog predict -i text_input="hello" -i scale=2.0`

cog --version

Debug

Known issues

breakingIn v0.17.0+, `setup()` and `predict()` methods are synchronous by default. If your model's operations are truly asynchronous (e.g., awaiting external I/O), you *must* explicitly declare these methods as `async def`.

fix

Prefix `def` with `async` (e.g., `async def setup(self):`) for asynchronous operations. Ensure your code properly `await`s async calls within these methods.

affects: 0.17.0+

breakingIn v0.17.0+, `Input()` arguments without a default value now default to `None` if not provided by the client, instead of Pydantic raising an error. This can lead to `None` type errors in your `predict` method if you expect a non-null value.

fix

Either provide a default value to `Input()` (e.g., `Input(default=...)`) or explicitly handle `None` checks in your `predict` method for any input that might be optional.

affects: 0.17.0+

gotchaCog relies on Docker to build and run model containers. Docker Desktop (or equivalent Docker engine) must be installed and running on your system for `cog build`, `cog push`, and local `cog predict` commands to function.

fix

Install Docker Desktop (for Windows/macOS) or Docker Engine (for Linux) and ensure the Docker daemon is running before using Cog commands.

affects: All

gotchaThe `cog.yaml` configuration file is crucial for defining your model's environment (e.g., Python version, system packages, `requirements.txt` path). Incorrect or missing configuration often leads to build failures or runtime errors within the container.

fix

Always initialize `cog.yaml` using `cog init` and carefully specify `python_version`, `build.python_packages`, `build.system_packages`, and `build.python_version` as needed for your model. Double-check paths to `requirements.txt` and other build files.

affects: All

deprecatedThe `extra_model_headers` field in `cog.yaml` has been removed in v0.17.0+ and will cause an error if present.

fix

Remove `extra_model_headers` from your `cog.yaml` file. If you relied on this for custom headers, you may need to implement a custom HTTP handler or find an alternative approach.

affects: 0.17.0+

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'cog'

This error typically occurs when the `cog` Python package (which provides `BasePredictor`, `Path`, etc.) is not found in the Python environment where a `cog` command (like `cog build` or `cog predict`) is attempting to set up or run your model, or when an internal Cog process tries to import its own modules.

fix

Ensure the `cog` CLI tool is correctly installed in your environment. When running `cog build`, Cog will automatically install its Python SDK wheel into the Docker image it creates. If you're running local Python scripts that import `cog`'s types outside of the `cog build` process, you might need to explicitly install the `cog` Python package in your local environment using `pip install cog`.

python_version is now required in the build: section of cog.yaml

This is a breaking change introduced in Cog versions 0.16.0 and later, making it mandatory to explicitly declare the Python version in the `cog.yaml` file for all models. Python 3.8 and 3.9 are also no longer supported in recent Cog versions.

fix

Add a `python_version` field under the `build` section in your `cog.yaml` file, specifying a supported Python version (e.g., '3.10', '3.11', '3.12', or '3.13').

Example:
```yaml
build:
  python_version: "3.10"
  # ... other build configurations
```

ERROR: failed to solve: failed to resolve source metadata for r8.im/cog-base:cudaXX.X-pythonYY.Y: no match for platform in manifest: not found

This error occurs during `cog build` when the Docker base image specified (often a Replicate `cog-base` image with specific CUDA/Python versions) does not support the underlying architecture of the machine where the build is being executed (e.g., trying to build a CUDA-enabled image on an ARM-based machine like Apple Silicon or an `aarch64` EC2 instance without proper multi-platform build setup).

fix

1. **Install and configure Docker Buildx:** Ensure Docker Buildx is properly set up by running `docker buildx install` and `docker buildx create --use`.
2. **Adjust for architecture:** If you are on an ARM-based machine (e.g., `aarch64`) and do not require GPU, set `gpu: false` in your `cog.yaml` to use a CPU-only base image, which has broader platform support. If you need GPU support on ARM, ensure you are using a base image specifically built for that architecture and a compatible `cuda` version.
3. **Buildx driver:** In CI/CD environments, ensure the `buildx` driver is correctly configured, sometimes explicitly setting it to `docker` instead of `docker-container` can resolve issues: `docker buildx use default` or similar configuration in your CI script.

cog.File is deprecated. Use cog.Path instead.

The `cog.File` type, previously used for handling file inputs and outputs in `predict.py`, has been deprecated. It has been replaced by `cog.Path` to provide better integration with Python's `pathlib.Path` module and enhanced functionality.

fix

Replace all instances of `cog.File` with `cog.Path` in your `predict.py` file and any other related model code.

Example:
```python
# Before (deprecated)
from cog import BasePredictor, File

# After (correct)
from cog import BasePredictor, Path
```

Upgrade

Version history

0.22.0latest on PyPI · released Aug 14, 2026

Audit

Dependencies

dockerrequiredCog builds and runs Docker containers; Docker engine must be installed and running.

Agent activity

22 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/replicate/cog ↗

packagehttps://pypi.org/project/cog/ ↗

homepagehttps://cog.run ↗