Skip to main content
Run a prediction on a model. Can build and run from the current directory, or run against a pre-built Docker image.

​
Usage

cog predict [image] [flags]
If image is provided, it runs the prediction on that Docker image (must be a Cog-built image). Otherwise, it builds the model in the current directory and runs the prediction.

​
Flags

​
-i, --input
string[]
Inputs in the form name=value. If value is prefixed with @, it’s read from a file. Can be specified multiple times.
cog predict -i prompt="a photo of a cat"
cog predict -i [email protected]
cog predict -i prompt="sunset" -i width=1024 -i height=768
​
--json
string
Pass inputs as a JSON object, read from a file (@inputs.json) or via stdin (@-)
echo '{"prompt": "a cat"}' | cog predict --json @-
cog predict --json @inputs.json
​
-o, --output
string
Output path for saving results
cog predict -i [email protected] -o output.png
​
-e, --env
string[]
Environment variables in the form name=value. Can be specified multiple times.
cog predict -e DEBUG=true -i prompt="test"
​
-f, --file
string
default:"cog.yaml"
The name of the config file
cog predict -f custom-config.yaml -i [email protected]
​
--gpus
string
GPU devices to add to the container, in the same format as docker run --gpus
cog predict --gpus all -i prompt="test"
cog predict --gpus '"device=0,1"' -i prompt="test"
​
--setup-timeout
integer
default:"300"
The timeout for container setup in seconds
cog predict --setup-timeout 600 -i [email protected]
​
--use-replicate-token
boolean
Pass REPLICATE_API_TOKEN from local environment into the model context
cog predict --use-replicate-token -i prompt="test"
​
--progress
string
default:"auto"
Set type of build progress output: auto, tty, plain, or quiet
​
--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

​
Run a prediction with named inputs

cog predict -i prompt="a photo of a cat"
Output: 
Building Docker image from environment in cog.yaml...

[+] Building 2.3s (12/12) FINISHED

Starting Docker image and running setup()...

Running prediction...

"A curious tabby cat sitting on a windowsill, photographed in natural light"

​
Pass a file as input

cog predict -i [email protected]
The @ prefix tells Cog to read the file contents: 
Running prediction...

{
  "label": "tabby_cat",
  "confidence": 0.94
}

​
Save output to a file

cog predict -i [email protected] -o output.png
Output: 
Running prediction...

Written output to: output.png

​
Pass multiple inputs

cog predict -i prompt="sunset over mountains" -i width=1024 -i height=768 -i num_outputs=4

​
Run against a pre-built image

Instead of building from the current directory: 
cog predict r8.im/username/my-model -i prompt="hello"
Or with a local image: 
cog predict my-model:latest -i prompt="hello"

​
Pass inputs as JSON

From stdin: 
echo '{"prompt": "a cat", "num_outputs": 4}' | cog predict --json @-
From a file: 
cog predict --json @inputs.json
Where inputs.json contains: 
{
  "prompt": "a photo of a cat",
  "width": 1024,
  "height": 768
}

​
Pass files in JSON mode

In JSON mode, prefix file paths with @: 
{
  "image": "@photo.jpg",
  "mask": "@mask.png"
}

​
Run with environment variables

cog predict -e DEBUG=true -e MODEL_CACHE=/tmp/cache -i prompt="test"

​
Specify GPU usage

# Use all available GPUs
cog predict --gpus all -i prompt="test"

# Use specific GPUs
cog predict --gpus '"device=0,1"' -i prompt="test"

# Run without GPU
cog predict --gpus "" -i prompt="test"

​
Handle large models with longer setup timeout

cog predict --setup-timeout 600 -i [email protected]

​
Input Types

Cog automatically handles different input types:

​
Files

Prefix with @ to read from disk: 
cog predict -i [email protected] -i [email protected]

​
Strings

cog predict -i prompt="hello world" -i text="some text"

​
Numbers

cog predict -i width=1024 -i temperature=0.8

​
Booleans

cog predict -i use_refiner=true -i debug=false

​
Output Handling

​
String outputs

Printed directly to stdout: 
"Generated text output"

​
File outputs

Automatically saved to disk: 
Written output to: output.0.png
Written output to: output.1.png

​
JSON outputs

Pretty-printed: 
{
  "result": "success",
  "score": 0.95
}

​
Array outputs

For file arrays, each file is numbered: 
cog predict -i prompt="cats" -o result.png
Produces: 
Written output to: result.0.png
Written output to: result.1.png
Written output to: result.2.png

​
Error Handling

​
Prediction failures

When a prediction fails, Cog exits with a non-zero status code: 
cog predict -i invalid=input
# Exit code: 1

​
Missing inputs

Cog validates inputs against your model’s schema: 
Error: Missing required input 'prompt'

​
Invalid image name

If you forget -i, Cog detects the mistake: 
cog predict [email protected]
# Error: Invalid image name '[email protected]'. Did you forget `-i`?

​
GPU Support

Cog automatically detects when your model needs a GPU:
  • If cog.yaml specifies gpu: true, Cog uses --gpus all by default
  • If GPU drivers are missing, Cog automatically retries without GPU
  • You can override with --gpus flag

​
How It Works

  1. Build phase (if no image specified):
    • Reads cog.yaml
    • Builds a Docker image with your environment
    • Mounts current directory as a volume
  2. Setup phase:
    • Starts Docker container
    • Runs your model’s setup() method
    • Waits up to --setup-timeout seconds
  3. Prediction phase:
    • Validates inputs against model schema
    • Runs your model’s predict() method
    • Handles output based on type
  4. Cleanup:
    • Stops the container
    • Removes temporary resources

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us