{"id":2438,"library":"cog","title":"Cog (Replicate)","description":"Cog is an open-source tool for packaging machine learning models into standard Docker containers. It allows you to define a Python `Predictor` class with `setup` and `predict` methods, which Cog then uses to build a Docker image for local testing or deployment to platforms like Replicate. The current version is 0.17.2, and it receives frequent minor updates with occasional major releases introducing significant architectural changes.","status":"active","version":"0.17.2","language":"en","source_language":"en","source_url":"https://github.com/replicate/cog","tags":["machine learning","MLOps","containerization","docker","model deployment","replicate"],"install":[{"cmd":"pip install cog","lang":"bash","label":"Install Cog Python SDK"},{"cmd":"curl -o /usr/local/bin/cog -L 'https://github.com/replicate/cog/releases/latest/download/cog_$(uname -s)_$(uname -m)' && chmod +x /usr/local/bin/cog","lang":"bash","label":"Install Cog CLI (Linux/macOS)"}],"dependencies":[{"reason":"Cog builds and runs Docker containers; Docker engine must be installed and running.","package":"docker","optional":false}],"imports":[{"symbol":"BasePredictor","correct":"from cog import BasePredictor"},{"symbol":"Input","correct":"from cog import Input"},{"note":"Used for file inputs/outputs, typically `pathlib.Path` or `str` representations of paths.","symbol":"Path","correct":"from cog import Path"},{"note":"Used for programmatic interaction with the Replicate API, not for defining models.","symbol":"replicate","correct":"from cog import replicate"}],"quickstart":{"code":"from cog import BasePredictor, Input, Path\nimport torch\n\nclass Predictor(BasePredictor):\n    def setup(self):\n        \"\"\"Load the model into memory to make running multiple predictions efficient\"\"\"\n        # Example: self.model = torch.load(\"./weights.pth\")\n        self.model = \"a dummy model\"\n\n    def predict(\n        self,\n        text_input: str = Input(description=\"A text input\"),\n        scale: float = Input(description=\"Factor to scale by\", default=1.5)\n    ) -> str:\n        \"\"\"Run a single prediction on the model\"\"\"\n        # Example: processed_input = self.preprocess(text_input)\n        # output = self.model(processed_input, scale)\n        output = f\"Processed '{text_input}' with scale {scale}\"\n        return output\n\n# To run locally with Cog CLI:\n# 1. Create a cog.yaml file: `cog init`\n# 2. Add dependencies (e.g., torch) to requirements.txt\n# 3. Run prediction: `cog predict -i text_input=\"hello\" -i scale=2.0`","lang":"python","description":"Define a `Predictor` class inheriting from `BasePredictor`. Implement `setup()` to load your model and `predict()` to handle inference. `Input` specifies prediction inputs with types, descriptions, and defaults. `Path` is used for file-based inputs/outputs."},"warnings":[{"fix":"Prefix `def` with `async` (e.g., `async def setup(self):`) for asynchronous operations. Ensure your code properly `await`s async calls within these methods.","message":"In v0.17.0+, `setup()` and `predict()` methods are synchronous by default. If your model's operations are truly asynchronous (e.g., awaiting external I/O), you *must* explicitly declare these methods as `async def`.","severity":"breaking","affected_versions":"0.17.0+"},{"fix":"Either provide a default value to `Input()` (e.g., `Input(default=...)`) or explicitly handle `None` checks in your `predict` method for any input that might be optional.","message":"In v0.17.0+, `Input()` arguments without a default value now default to `None` if not provided by the client, instead of Pydantic raising an error. This can lead to `None` type errors in your `predict` method if you expect a non-null value.","severity":"breaking","affected_versions":"0.17.0+"},{"fix":"Install Docker Desktop (for Windows/macOS) or Docker Engine (for Linux) and ensure the Docker daemon is running before using Cog commands.","message":"Cog relies on Docker to build and run model containers. Docker Desktop (or equivalent Docker engine) must be installed and running on your system for `cog build`, `cog push`, and local `cog predict` commands to function.","severity":"gotcha","affected_versions":"All"},{"fix":"Always initialize `cog.yaml` using `cog init` and carefully specify `python_version`, `build.python_packages`, `build.system_packages`, and `build.python_version` as needed for your model. Double-check paths to `requirements.txt` and other build files.","message":"The `cog.yaml` configuration file is crucial for defining your model's environment (e.g., Python version, system packages, `requirements.txt` path). Incorrect or missing configuration often leads to build failures or runtime errors within the container.","severity":"gotcha","affected_versions":"All"},{"fix":"Remove `extra_model_headers` from your `cog.yaml` file. If you relied on this for custom headers, you may need to implement a custom HTTP handler or find an alternative approach.","message":"The `extra_model_headers` field in `cog.yaml` has been removed in v0.17.0+ and will cause an error if present.","severity":"deprecated","affected_versions":"0.17.0+"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}