Cog: Containers for machine learning
Cog is an open-source tool that lets you package machine learning models in a standard, production-ready container.
You can deploy your packaged model to your own infrastructure, or to Replicate.
Highlights
-
📦 Docker containers without the pain. Writing your own
Dockerfilecan be a bewildering process. With Cog, you define your environment with a simple configuration file and it generates a Docker image with all the best practices: Nvidia base images, efficient caching of dependencies, installing specific Python versions, sensible environment variable defaults, and so on. -
🤬️ No more CUDA hell. Cog knows which CUDA/cuDNN/PyTorch/Tensorflow/Python combos are compatible and will set it all up correctly for you.
-
✅ Define the inputs and outputs for your model with standard Python. Then, Cog generates an OpenAPI schema and validates the inputs and outputs.
-
🎁 Automatic HTTP inference server: Your model's types are used to dynamically generate a RESTful HTTP API using a high-performance Rust/Axum server.
-
🚀 Ready for production. Deploy your model anywhere that Docker images run. Your own infrastructure, or Replicate.
How it works
Define the Docker environment your model runs in with cog.yaml:
build:
gpu: true
system_packages:
- "libgl1"
- "libglib2.0-0"
python_version: "3.13"
python_requirements: requirements.txt
run: "run.py:Runner"
Define how your model runs with run.py:
from cog import BaseRunner, Input, Path
import torch
class Runner(BaseRunner):
def setup(self):
"""Load the model into memory to make running multiple inferences efficient"""
self.model = torch.load("./weights.pth")
# The arguments and types the model takes as input
def run(self,
image: Path = Input(description="Grayscale input image")
) -> Path:
"""Run the model"""
processed_image = preprocess(image)
output = self.model(processed_image)
return postprocess(output)
In the above we accept a path to the image as an input, and return a path to our transformed image after running it through our model.
Now, you can run the model:
$ cog run -i image=@input.jpg
--> Building Docker image...
--> Running...
--> Output written to output.jpg
Or, build a Docker image for deployment:
$ cog build -t my-classification-model
--> Building Docker image...
--> Built my-classification-model:latest
$ docker run -d -p 5000:5000 --gpus all my-classification-model
$ curl http://localhost:5000/predictions -X POST \
-H 'Content-Type: application/json' \
-d '{"input": {"image": "https://.../input.jpg"}}'
Or, combine build and run via the serve command:
$ cog serve -p 8080
$ curl http://localhost:8080/predictions -X POST \
-H 'Content-Type: application/json' \
-d '{"input": {"image": "https://.../input.jpg"}}'
Why are we building this?
It's really hard for researchers to ship machine learning models to production.
Part of the solution is Docker, but it is so complex to get it to work: Dockerfiles, pre-/post-processing, Flask servers, CUDA versions. More often than not the researcher has to sit down with an engineer to get the damn thing deployed.
Andreas and Ben created Cog. Andreas used to work at Spotify, where he built tools for building and deploying ML models with Docker. Ben worked at Docker, where he created Docker Compose.
We realized that, in addition to Spotify, other companies were also using Docker to build and deploy machine learning models. Uber and others have built similar systems. So, we're making an open source version so other people can do this too.
Hit us up if you're interested in using it or want to collaborate with us. We're on Discord or email us at team@replicate.com.
Prerequisites
- macOS, Linux or Windows 11. Cog works on macOS, Linux and Windows 11 with WSL 2
- Docker. Cog uses Docker to create a container for your model. You'll need to install Docker before you can run Cog. If you install Docker Engine instead of Docker Desktop, you will need to install Buildx as well.
Install
Choose your platform for installation instructions.
macOS
The easiest way to install Cog on macOS is with Homebrew:
brew install replicate/tap/cog
You can also use the install script:
# bash, zsh, and other shells
sh <(curl -fsSL https://cog.run/install.sh)
# fish shell
sh (curl -fsSL https://cog.run/install.sh | psub)
# download with wget and run in a separate command
wget -qO- https://cog.run/install.sh
sh ./install.sh
Or install manually:
sudo curl -o /usr/local/bin/cog -L "https://github.com/replicate/cog/releases/latest/download/cog_$(uname -s)_$(uname -m | sed 's/aarch64/arm64/')"
sudo chmod +x /usr/local/bin/cog
sudo xattr -d com.apple.quarantine /usr/local/bin/cog 2>/dev/null || true
If you see a Gatekeeper warning saying the binary "cannot be opened because the developer cannot be verified", run:
sudo xattr -d com.apple.quarantine /usr/local/bin/cog
Linux
You can install Cog using the install script:
# bash, zsh, and other shells
sh <(curl -fsSL https://cog.run/install.sh)
# fish shell
sh (curl -fsSL https://cog.run/install.sh | psub)
# download with wget and run in a separate command
wget -qO- https://cog.run/install.sh
sh ./install.sh
Or install manually:
sudo curl -o /usr/local/bin/cog -L "https://github.com/replicate/cog/releases/latest/download/cog_$(uname -s)_$(uname -m | sed 's/aarch64/arm64/')"
sudo chmod +x /usr/local/bin/cog
Windows
Cog does not natively support Windows, but you can run it on Windows 11 using WSL 2. Once WSL 2 is set up, follow the Linux installation instructions above.
Docker
To install Cog inside a Docker image:
RUN sh -c "INSTALL_DIR=\"/usr/local/bin\" SUDO=\"\" $(curl -fsSL https://cog.run/install.sh)"
Upgrade
If you're using macOS and you previously installed Cog with Homebrew, run the following:
brew upgrade replicate/tap/cog
Otherwise, you can upgrade to the latest version by running the same commands you used to install it.
Development
See CONTRIBUTING.md for how to set up a development environment and build from source.
Next steps
- Get started with an example model
- Get started with your own model
- Using Cog with notebooks
- Using Cog with Windows 11
- Browse the example models in this repo
- Deploy models with Cog
cog.yamlreference to learn how to define your model's environment- Run interface reference to learn how the
Runnerinterface works - Training interface reference to learn how to add a fine-tuning API to your model
- HTTP API reference to learn how to use the HTTP API that models serve
Need help?
Contributors ✨
Thanks goes to these wonderful people (emoji key):
This project follows the all-contributors specification. Contributions of any kind welcome!
3 maintainers
Metadata
3 maintainers
Release files for cog 0.23.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| cog-0.23.0.tar.gz | 19.3 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| cog-0.23.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 19.3 MB
Release files / cog-0.23.0.tar.gz
| Download URL | cog-0.23.0.tar.gz |
|---|---|
| Size | 19.3 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
90f04c157b648fd94fc42605ad49eb89c8b92fd943562a9882444a42b1759b23
|
|
BLAKE2b-256 checksum How to use checksums |
e79a8dd3cc323fb30aa1a6cafabc41fe8baad0d14b4aa97b1da86289b297fad4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 22, 2026.
Transparency logRelease files / cog-0.23.0-py3-none-any.whl
| Download URL | cog-0.23.0-py3-none-any.whl |
|---|---|
| Size | 44.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
de51c4b19eca1480875bd58edd88c14fe03a4a7404779e304c449175f3e12e89
|
|
BLAKE2b-256 checksum How to use checksums |
f18825f6bc6ee987875acb45f53058dd5baaade08b55b1ad0118349e2fb71edd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 22, 2026.
Transparency log
