Skip to main content
cog.yaml defines how to build a Docker image and how to run predictions on your model inside that image. It has three main sections: build, image, and predict.

​
Example Configuration

build:
  python_version: "3.11"
  python_requirements: requirements.txt
  system_packages:
    - "ffmpeg"
    - "git"
predict: "predict.py:Predictor"
Run cog init to generate an annotated cog.yaml file that can be used as a starting point for setting up your model.

​
Top-Level Properties

​
build
object
required
Describes how to build the Docker image your model runs in. See Build Configuration for all available options.
​
image
string
The name given to built Docker images. If you want to push to a registry, this should also include the registry name.
image: "r8.im/your-username/your-model"
If you don’t set this, a name will be generated from the directory name. When set, you can run cog push without specifying the model name.
r8.im is Replicate’s registry, but this can be any Docker registry.
​
predict
string
The pointer to the Predictor object in your code, which defines how predictions are run on your model.
predict: "predict.py:Predictor"
​
train
string
The pointer to the Predictor object in your code that defines how training runs on your model.
train: "train.py:Trainer"
​
concurrency
object
Describes the concurrency capabilities of the model. Added in cog 0.14.0.
​
environment
array
A list of environment variables to make available during builds and at runtime, in the format NAME=value.
environment:
  - "DEBUG=true"
  - "MAX_WORKERS=4"
​
weights
array
A list of weight files or directories to include in the model.
weights:
  - source: weights/model.safetensors
    target: /cache/model.safetensors

​
Build Configuration

The build section describes how to build the Docker image your model runs in.
​
build.python_version
string
required
The minor (3.11) or patch (3.11.1) version of Python to use.
build:
  python_version: "3.11.1"
Cog supports Python 3.10, 3.11, 3.12, and 3.13. If you don’t define a version, Cog will use the latest version of Python 3.13 or a version of Python that is compatible with the versions of PyTorch or TensorFlow you specify.
These are the versions supported in the Docker container, not your host machine. You can run any version(s) of Python you wish on your host machine.
​
build.python_requirements
string
A pip requirements file specifying the Python packages to install.
build:
  python_requirements: requirements.txt
This follows the standard requirements.txt format.
Your cog.yaml file can set either python_packages or python_requirements, but not both. Use python_requirements when you need to configure options like --extra-index-url or --trusted-host to fetch Python package dependencies.

​
Installing Git-hosted packages

To install Git-hosted Python packages, add git to the system_packages list, then use the git+https:// syntax:cog.yaml:
build:
  system_packages:
    - "git"
  python_requirements: requirements.txt
requirements.txt:
git+https://github.com/huggingface/transformers
You can also pin Python package installations to a specific git commit:
git+https://github.com/huggingface/transformers@2d1602a
You can use a shortened prefix of the 40-character git commit SHA, but you must use at least six characters.
​
build.python_packages
array
DEPRECATED: This will be removed in future versions, please use python_requirements instead.
A list of Python packages to install from the PyPI package index, in the format package==version.
build:
  python_packages:
    - pillow==8.3.1
    - tensorflow==2.5.0
Your cog.yaml file can set either python_packages or python_requirements, but not both.
​
build.system_packages
array
A list of Ubuntu APT packages to install.
build:
  system_packages:
    - "ffmpeg"
    - "libavcodec-dev"
​
build.gpu
boolean
default:false
Enable GPUs for this model. When enabled, the nvidia-docker base image will be used, and Cog will automatically figure out what versions of CUDA and cuDNN to use based on the version of Python, PyTorch, and Tensorflow that you are using.
build:
  gpu: true
When you use cog run or cog predict, Cog will automatically pass the --gpus=all flag to Docker. When you run a Docker image built with Cog, you’ll need to pass this option to docker run.
​
build.cuda
string
Cog automatically picks the correct version of CUDA to install, but this lets you override it by specifying the minor (11.8) or patch (11.8.0) version of CUDA to use.
build:
  cuda: "11.8"
​
build.cudnn
string
Cog automatically picks the correct version of cuDNN to install, but this lets you override it for whatever reason.
build:
  cudnn: "8"
​
build.run
array
A list of setup commands to run in the environment after your system packages and Python packages have been installed. If you’re familiar with Docker, it’s like a RUN instruction in your Dockerfile.
build:
  run:
    - curl -L https://github.com/cowsay-org/cowsay/archive/refs/tags/v3.7.0.tar.gz | tar -xzf -
    - cd cowsay-3.7.0 && make install
Your code is not available to commands in run. This is so we can build your image efficiently when running locally.

​
Using secret mounts

Each command in run can be either a string or a dictionary with secret mounts:
build:
  run:
    - command: pip install
      mounts:
        - type: secret
          id: pip
          target: /etc/pip.conf
You can use secret mounts to securely pass credentials to setup commands, without baking them into the image. For more information, see the Dockerfile reference.
​
build.pre_install
array
A list of setup commands to run in the environment before your Python packages are installed.
build:
  pre_install:
    - apt-get update
    - apt-get install -y custom-package
​
build.sdk_version
string
Pin the version of the cog Python SDK installed in the container. Accepts a PEP 440 version string. When omitted, the latest release is installed.
build:
  python_version: "3.12"
  sdk_version: "0.18.0"
Pre-release versions are also supported:
build:
  sdk_version: "0.18.0a1"
When a pre-release sdk_version is set, --pre is automatically passed to the pip install commands for both cog and coglet, so pip will resolve matching pre-release packages.
The minimum supported version is 0.16.0. Specifying an older version will cause cog build to fail with an error.
The COG_SDK_WHEEL environment variable takes precedence over sdk_version. See Environment variables for details.

​
Tests Configuration

​
tests
array
A list of test cog commands to run.
tests:
  - predict:
      input:
        text: "hello world"

Build docs developers (and LLMs) love

Get started for freeTalk to us