cog push - Cog

Build a Docker image from cog.yaml and push it to a container registry. Cog can push to any OCI-compliant registry. When pushing to Replicate’s registry (r8.im), run cog login first to authenticate.

Usage

cog push [IMAGE] [flags]

The IMAGE argument specifies the destination in the format registry.example.com/username/model-name. If not provided, Cog uses the image field from cog.yaml.

Flags

-f, --file

string

default:"cog.yaml"

The name of the config file

cog push -f custom-config.yaml

--no-cache

boolean

Do not use cache when building the image

cog push r8.im/username/model --no-cache

--separate-weights

boolean

Separate model weights from code in image layers. This is a Replicate-specific optimization that enables faster deploys when only code changes.

cog push r8.im/username/model --separate-weights

--progress

string

default:"auto"

Set type of build progress output: auto, tty, plain, or quiet

cog push r8.im/username/model --progress=plain

--secret

string[]

Secrets to pass to the build environment in the form id=foo,src=/path/to/file. Can be specified multiple times.

cog push r8.im/username/model --secret id=pip_config,src=~/.pip/pip.conf

--openapi-schema

string

Load OpenAPI schema from a file instead of generating it

cog push r8.im/username/model --openapi-schema schema.json

--use-cog-base-image

boolean

default:"true"

Use pre-built Cog base image for faster cold boots

--use-cuda-base-image

string

default:"auto"

Use Nvidia CUDA base image: true, false, or auto

Examples

Push to Replicate

cog push r8.im/your-username/my-model

Output:

Building Docker image from environment in cog.yaml as r8.im/your-username/my-model...

[+] Building 45.2s (15/15) FINISHED
 => [internal] load build definition from Dockerfile
 => transferring dockerfile: 2.34kB
...

Pushing image r8.im/your-username/my-model...
ab12cd34: Pushing [==========================>] 2.048 MB/2.048 MB
ef56gh78: Pushing [===================>       ] 1.5 MB/2.0 MB
...

Pushed r8.im/your-username/my-model
https://replicate.com/your-username/my-model

Push to any OCI registry

cog push registry.example.com/your-username/model-name

Works with:

Docker Hub: docker.io/username/model
GitHub Container Registry: ghcr.io/username/model
AWS ECR: 123456789.dkr.ecr.us-east-1.amazonaws.com/model
Google Artifact Registry: us-docker.pkg.dev/project/repo/model
Azure Container Registry: myregistry.azurecr.io/model

Push with separate weights

Optimizes image layers for faster updates (Replicate only):

cog push r8.im/your-username/my-model --separate-weights

Benefits:

Faster deploys when only code changes
More efficient storage
Better layer caching

Push from cog.yaml

Add the image name to cog.yaml:

image: "r8.im/your-username/my-model"
build:
  python_version: "3.12"
  python_requirements: requirements.txt
predict: "predict.py:Predictor"

Then simply run:

cog push

Push with no cache

Force a fresh build:

cog push r8.im/username/model --no-cache

Useful when:

Dependencies have changed
You need to clear cached layers
Debugging build issues

Push with secrets

Pass secrets for private registries or packages:

cog push r8.im/username/model \
  --secret id=pip_config,src=~/.pip/pip.conf \
  --secret id=github_token,src=./github_token.txt

Authentication

Replicate (r8.im)

Authenticate with Replicate:

cog login

This opens your browser to get a token. Alternatively, use a token directly:

cog login --token-stdin < token.txt

Other registries

Use Docker’s authentication:

# Docker Hub
docker login

# Other registries
docker login registry.example.com

Cog uses your Docker credentials automatically.

GitHub Container Registry

echo $GITHUB_TOKEN | docker login ghcr.io -u USERNAME --password-stdin
cog push ghcr.io/username/model

AWS ECR

aws ecr get-login-password --region us-east-1 | \
  docker login --username AWS --password-stdin \
  123456789.dkr.ecr.us-east-1.amazonaws.com
cog push 123456789.dkr.ecr.us-east-1.amazonaws.com/model

Registry-Specific Features

Replicate (r8.im)

When pushing to Replicate:

Automatic versioning: Each push creates a new version
Web UI: View at https://replicate.com/username/model
Separate weights: Use --separate-weights for optimization
Automatic deployment: Model is immediately available via API

Example output:

Pushed r8.im/your-username/my-model
https://replicate.com/your-username/my-model

Your model is now available:
  curl -X POST https://api.replicate.com/v1/predictions \
    -H "Authorization: Bearer $REPLICATE_API_TOKEN" \
    -d '{"version": "abc123...", "input": {...}}'

Other registries

Standard OCI push:

Standard Docker registry protocol
Standard layer compression
Compatible with any Docker tooling

Build Process

When you run cog push, Cog:

Validates your cog.yaml configuration
Builds a Docker image (same as cog build)
Tags the image with the specified name
Pushes to the registry:
- Compresses layers
- Shows progress for each layer
- Handles authentication
Reports success with URL (for Replicate)

Image Contents

The pushed image contains:

Base system: Ubuntu with CUDA (if GPU enabled)
Python environment: Specified Python version and packages
Your code: All files in the current directory
Model weights: Embedded in the image (or separate layer with --separate-weights)
Cog runtime: HTTP server and prediction infrastructure
Metadata: OpenAPI schema, model configuration

Layer Structure

Standard build

┌─────────────────────┐
│ Your code & weights │  ← Changes often
├─────────────────────┤
│ Python packages     │  ← Changes sometimes
├─────────────────────┤
│ System packages     │  ← Rarely changes
├─────────────────────┤
│ Base image (CUDA)   │  ← Cached
└─────────────────────┘

With —separate-weights

┌─────────────────────┐
│ Your code          │  ← Changes often, small
├─────────────────────┤
│ Model weights      │  ← Changes rarely, large
├─────────────────────┤
│ Python packages    │  ← Changes sometimes
├─────────────────────┤
│ System packages    │  ← Rarely changes
├─────────────────────┤
│ Base image (CUDA)  │  ← Cached
└─────────────────────┘

Separate weights improve cache efficiency when you update code but not weights.

Progress Output

Default (auto)

ab12cd34: Pushing [==========================>] 2.048 MB/2.048 MB
ef56gh78: Pushing [===================>       ] 1.5 MB/2.0 MB
ij90kl12: Pushed

Plain (for CI/CD)

cog push r8.im/username/model --progress=plain

Output:

#1 [internal] load build definition from Dockerfile
#1 transferring dockerfile: 2.34kB
#1 DONE 0.0s
...

Quiet

cog push r8.im/username/model --progress=quiet

Minimal output, only errors and final result.

Error Handling

Build failures

If the build fails, Cog stops before pushing:

Error: Failed to install package 'invalid-package'

Fix the issue and try again.

Push failures

Common issues: Authentication error:

Error: authentication required

Solution: Run cog login (for Replicate) or docker login (for other registries) Network error:

Error: failed to push layer: connection timeout

Solution: Check your network connection and try again Permission error:

Error: permission denied

Solution: Verify you have push access to the repository

Registry errors

Invalid image name:

Error: no provider found for image 'invalid-name'

Solution: Use correct format: registry.example.com/username/model Repository doesn’t exist:

Error: repository not found

Solution: Create the repository on your registry first

Performance Tips

Use layer caching

Order your cog.yaml to maximize cache hits:

build:
  # These rarely change (good for caching)
  python_version: "3.12"
  system_packages:
    - ffmpeg
  
  # These change sometimes
  python_requirements: requirements.txt
  
  # Your code changes often (last layer)
predict: "predict.py:Predictor"

Use —separate-weights

For large models, separate weights from code:

cog push r8.im/username/model --separate-weights

Optimize dependencies

Only install what you need:

# ❌ Don't install everything
transformers
torch
torchvision
torchaudio

# ✅ Install only what you use
transformers==4.30.0
torch==2.0.0

Use fast network

Pushing large images can take time. Use a fast, stable network connection.

CI/CD Integration

GitHub Actions

name: Push to Replicate
on:
  push:
    branches: [main]
jobs:
  push:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: replicate/setup-cog@v1
      - name: Push to Replicate
        env:
          REPLICATE_API_TOKEN: ${{ secrets.REPLICATE_API_TOKEN }}
        run: |
          echo $REPLICATE_API_TOKEN | cog login --token-stdin
          cog push r8.im/username/model

GitLab CI

push:
  image: replicate/cog:latest
  script:
    - echo $REPLICATE_API_TOKEN | cog login --token-stdin
    - cog push r8.im/username/model
  only:
    - main

CLI Commands

Python SDK

HTTP API

Redis Queue

​Usage

​Flags

​Examples

​Push to Replicate

​Push to any OCI registry

​Push with separate weights

​Push from cog.yaml

​Push with no cache

​Push with secrets

​Authentication

​Replicate (r8.im)

​Other registries

​GitHub Container Registry

​AWS ECR

​Registry-Specific Features

​Replicate (r8.im)

​Other registries

​Build Process

​Image Contents

​Layer Structure

​Standard build

​With —separate-weights

​Progress Output

​Default (auto)

​Plain (for CI/CD)

​Quiet

​Error Handling

​Build failures

​Push failures

​Registry errors

​Performance Tips

​Use layer caching

​Use —separate-weights

​Optimize dependencies

​Use fast network

​CI/CD Integration

​GitHub Actions

​GitLab CI

​See Also

Build docs developers (and LLMs) love

Usage

Flags

Examples

Push to Replicate

Push to any OCI registry

Push with separate weights

Push from cog.yaml

Push with no cache

Push with secrets

Authentication

Replicate (r8.im)

Other registries

GitHub Container Registry

AWS ECR

Registry-Specific Features

Replicate (r8.im)

Other registries

Build Process

Image Contents

Layer Structure

Standard build

With —separate-weights

Progress Output

Default (auto)

Plain (for CI/CD)

Quiet

Error Handling

Build failures

Push failures

Registry errors

Performance Tips

Use layer caching

Use —separate-weights

Optimize dependencies

Use fast network

CI/CD Integration

GitHub Actions

GitLab CI

See Also