Join us at Uncanny Spaces, a series of talks about ML and creativity. πŸš€

Push a model to Replicate

Learn how to package your own trained model using Cog and push it to Replicate.

You can make your model public so other people can run it, or you can make it private so only you can run it.


  • A trained model in a directory on your computer. Your model's saved weights, alongside any code that is needed to run it. If you don't already have your own trained model, you can use one from replicate/cog-examples.
  • macOS or Linux. You'll be using the Cog command-line tool to build and push your model. Cog works on macOS and Linux, but does not currently support Windows.
  • Docker. Cog uses Docker to create a container for your model. You'll need to install Docker before you can run Cog.

Create a Replicate account

Pushing models to Replicate is currently in closed beta while we iron out the wrinkles. If you don't have a invite, come talk to us in Discord or send an email to and tell us what you're thinking of making.

Sign up and add your credit card

To get started, you'll need to sign up and enter your billing info. There is no charge to sign up, and your predictions will be billed by the second.

Create a model page

Next you'll create a page for your model on Replicate. Visit to choose a name for your model, and specify whether it should be public or private.

Install Cog

Cog is an open source tool that makes it easy to put a machine learning model in a Docker container. Run this to install it:

sudo curl -o /usr/local/bin/cog -L`uname -s`_`uname -m`
sudo chmod +x /usr/local/bin/cog

More information about Cog and its full documentation are on GitHub.

Initialize Cog

To configure your project for use with Cog, you'll need to add two files to the directory containing your model:

Use the cog init command to generate these files in your project:

cd path/to/your/model
cog init

Define your dependencies

The cog.yaml file defines all the different things that need to be installed for your model to run. You can think of it as a simple way of defining a Docker image.

For example:

  python_version: "3.8"
    - "torch==1.7.0"

This will generate a Docker image with Python 3.8 and PyTorch 1.7 installed and various other sensible best-practices.

Using GPUs

To use GPUs, add the gpu: true option to the build section of your cog.yaml:

  gpu: true
  # ...

Cog will use the nvidia-docker base image and automatically figure out what versions of CUDA and cuDNN to use based on the version of Python, PyTorch, and Tensorflow that you are using.

Running commands

To run a command inside this environment, prefix it with cog run:

$ cog run python
βœ“ Building Docker image from cog.yaml... Successfully built 8f54020c8981
Running 'python' in Docker with the current directory mounted as a volume...

Python 3.8.10 (default, May 12 2021, 23:32:14)
[GCC 9.3.0] on linux
Type "help", "copyright", "credits" or "license" for more information.

This is handy for ensuring a consistent environment for development or training.

With cog.yaml, you can also install system packages and other things. Take a look at the full reference to see what else you can do.

Define how to run predictions

The next step is to update to define the interface for running predictions on your model. The generated by cog init looks something like this:

from cog import BasePredictor, Path, Input
import torch

class Predictor(BasePredictor):
    def setup(self):
        """Load the model into memory to make running multiple predictions efficient""" = torch.load("weights.pth")

    def predict(self,
            image: Path = Input(description="Image to enlarge"),
            scale: float = Input(description="Factor to scale image by", default=1.5)
    ) -> Path:
        """Run a single prediction on the model"""
        # ... pre-processing ...
        output =
        # ... post-processing ...
        return output

Edit your file and fill in the functions with your own model's setup and prediction code. You might need to import parts of your model from another file.

You should keep your model weights in the same directory as your file, or a subdirectory underneath it, and load them directly off disk in your setup() function, as shown in the example above. This will make it more efficient to load and easier to version because it will get copied into the Docker image that Cog produces.

You also need to define the inputs to your model as arguments to the predict() function, as demonstrated above. For each argument, you need to annotate with a type. The supported types are:

  • str: a string
  • int: an integer
  • float: a floating point number
  • bool: a boolean
  • cog.File: a file-like object representing a file
  • cog.Path: a path to a file on disk

You can provide more information about the input with the Input() function, as shown above. It takes these basic arguments:

  • description: A description of what to pass to this input for users of the model
  • default: A default value to set the input to. If this argument is not passed, the input is required. If it is explicitly set to None, the input is optional.
  • ge: For int or float types, the value should be greater than or equal to this number.
  • le: For int or float types, the value should be less than or equal to this number.
  • choices: For str or int types, a list of possible values for this input.

There are some more advanced options you can pass, too. For more details, take a look at the prediction interface documentation.

Next, add the line predict: "" to your cog.yaml, so it looks something like this:

  python_version: "3.8"
    - "torch==1.7.0"
predict: ""

That's it!

Test your model locally

To test this works, try running a prediction on the model:

$ cog predict -i image=@input.jpg
βœ“ Building Docker image from cog.yaml... Successfully built 664ef88bc1f4
βœ“ Model running in Docker image 664ef88bc1f4

Written output to output.png

To pass more inputs to the model, you can add more -i options:

$ cog predict -i image=@image.jpg -i scale=2.0

In this case it is just a number, not a file, so you don't need the @ prefix.

Push your model

Now that you've configured your model for use with Cog, it's time to publish it to the Replicate registry:

cog login
cog push

Note: You can also set the image property in your cog.yaml file. This allows you to run cog push without specifying the image, and also makes your Replicate model page more discoverable for folks reading your model's source code.

Run predictions

Once you've pushed your model to Replicate it will be visible on the website, and you can use the web-based form to run predictions using your model.

To run predictions in the cloud from your code, you can use the Python client library.

Install it from pip:

pip install replicate

Authenticate by setting your token in an environment variable:

export REPLICATE_API_TOKEN=<token>

Then, you can use it from your Python code:

$ python
>>> import replicate
>>> model = replicate.models.get("replicate/hello-world")
>>> model.predict(text="python")
"hello python"

To pass files as input, use a file handle or URL:

>>> model = replicate.models.get("replicate/resnet")
>>> model.predict(image=open("mystery.jpg", "rb"))
# or...
>>> model.predict(image="")

URLs are more efficient if your file is already in the cloud somewhere, or it is a large file.

If your model returns a file, it will be represented as a URL in the output. To fetch these files, you will need to pass an Authorization: Token <token> header to securely fetch the file, as documented in the HTTP API reference. (We are working on a better Python API for fetching files.)

For more details, see the full documentation on GitHub.

You can also run your model with the raw HTTP API. See the HTTP API reference for more details.