Skip to main content
This guide describes how to build a Docker image with Cog that fetches Python packages from a private registry during setup.

​
Overview

Cog supports using secret mounts to securely pass private registry credentials to pip during the build process, without baking them into the Docker image.
Be careful not to commit secrets in Git or include them in Docker images. If your Cog project contains any sensitive files, make sure they’re listed in .gitignore and .dockerignore.

​
Step 1: Create pip.conf

In a directory outside your Cog project, create a pip.conf file with an index-url set to the registry’s URL with embedded credentials.
pip.conf
[global]
index-url = https://username:[email protected]
Store this file outside your project directory to prevent accidentally committing it to version control.

​
Step 2: Configure cog.yaml

In your project’s cog.yaml file, add a setup command to run pip install with a secret configuration file mounted to /etc/pip.conf.
cog.yaml
build:
  run:
    - command: pip install
      mounts:
        - type: secret
          id: pip
          target: /etc/pip.conf

​
Configuration Options

​
command
string
required
The command to run during the build process (e.g., pip install).
​
mounts
array
required
An array of mount configurations for the command.

​
Step 3: Build with Secret

When building or pushing your model with Cog, pass the --secret option with an id matching the one specified in cog.yaml, along with a path to your local pip.conf file. 
cog build --secret id=pip,source=/path/to/pip.conf
Using a secret mount allows the private registry credentials to be securely passed to the pip install setup command, without baking them into the Docker image.

​
Caching Behavior

If you run cog build or cog push and then change the contents of a secret source file, the cached version of the file will be used on subsequent builds, ignoring any changes you made.
To update the contents of the target secret file, you have two options:
  1. Change the secret ID: Update both the id value in cog.yaml and the --secret option
  2. Bypass the cache: Pass the --no-cache option to cog build
# Option 1: Change the ID
cog build --secret id=pip-v2,source=/path/to/pip.conf

# Option 2: Bypass cache
cog build --secret id=pip,source=/path/to/pip.conf --no-cache

​
Additional Resources

For more information on secret mounts, see the Dockerfile reference documentation.

Build docs developers (and LLMs) love

Get started for freeTalk to us