> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://www.comet.com/docs/opik/self-host/local_deployment/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://www.comet.com/_mcp/server.

# Local deployment

> **Important:** If you're using or considering the enterprise version of Opik or Comet, reach out to [Sales@comet.com](mailto:Sales@comet.com) to access the enterprise deployment documentation.

To run Opik locally we recommend using [Docker Compose](https://docs.docker.com/compose/). It's easy to setup and allows you to get started in a couple of minutes **but** is not meant for production deployments. If you would like to run Opik in a production environment, we recommend using our [Kubernetes Helm chart](/self-host/kubernetes).

Before running the installation, make sure you have Docker and Docker Compose installed:

* [Docker](https://docs.docker.com/get-docker/)
* [Docker Compose](https://docs.docker.com/compose/install/)

> **Note**
>
> If you are using Mac or Windows, both `docker` and `docker compose` are included in the [Docker Desktop](https://docs.docker.com/desktop/) installation.

## Installation

To install Opik, you will need to clone the Opik repository and run the following commands:

#### Linux / Mac

```bash
# Clone the Opik repository
git clone https://github.com/comet-ml/opik.git

# Navigate to the opik folder

cd opik

# Start the Opik platform

./opik.sh

```

Opik will now be available at [http://localhost:5173](http://localhost:5173)

#### Windows

```powershell
# Clone the Opik repository
git clone https://github.com/comet-ml/opik.git

# Navigate to the opik folder
cd opik

# Start the Opik platform
powershell -ExecutionPolicy ByPass -c ".\opik.ps1"
```

Opik will now be available at [http://localhost:5173](http://localhost:5173)

> **Tip**
>
> In order to use the Opik Python SDK with your local Opik instance, you will need to run:
>
> ```bash
> pip install opik
>
> opik configure --use_local
> ```
>
> or in python:
>
> ```python
> import opik
>
> opik.configure(use_local=True)
> ```
>
> This will create a `~/.opik.config` file that will store the URL of your local Opik instance.

All the data logged to the Opik platform will be stored in the `~/opik` directory, which means that you can start and stop the Opik platform without losing any data.

### Installation script options

The `opik.sh` and `opik.ps1` scripts support the following options:

| Option         | Description                                                                              |
| -------------- | ---------------------------------------------------------------------------------------- |
| `--infra`      | Start only the infrastructure services (MySQL, Redis, ClickHouse, ZooKeeper, MinIO etc.) |
| `--backend`    | Start the infrastructure and backend services                                            |
| `--guardrails` | Enable guardrails, can be combined with the other start options                          |
| `--build`      | Build the containers from source before starting                                         |
| `--verify`     | Check that all containers are healthy                                                    |
| `--stop`       | Stop all containers                                                                      |
| `--clean`      | Stop all containers and remove all Opik data volumes                                     |
| `--help`       | Show all available options                                                               |

> **Warning**
>
> The `--clean` option removes all Opik data volumes. All data stored in the Opik platform will be lost and cannot be
> recovered.

Run `./opik.sh --help` (or `powershell -ExecutionPolicy ByPass -c ".\opik.ps1 --help"` on Windows) to see the full list of options.

## Stopping the Opik platform

You can stop the Opik server by running the following commands:

#### Linux / Mac

```bash
# Ensure you are running this command for the root of the Opik repository you cloned
./opik.sh --stop
```

#### Windows

```powershell
# Ensure you are running this command for the root of the Opik repository you cloned
powershell -ExecutionPolicy ByPass -c ".\opik.ps1 --stop"
```

**Note:** You can safely stop the Opik platform without losing any data.

## Upgrading and restarting the Opik platform

To upgrade or restart the Opik platform, you can simply run the `opik` script again:

#### Linux / Mac

```bash
# Ensure you are running this command for the root of the Opik repository you cloned
./opik.sh
```

#### Windows

```powershell
# Ensure you are running this command for the root of the Opik repository you cloned
powershell -ExecutionPolicy ByPass -c ".\opik.ps1"
```

> **Tip**
>
> Since the Docker Compose deployment is using mounted volumes, your data will ***not*** be lost when you upgrade Opik.
> You can also safely start and stop the Opik platform without losing any data.

## Advanced configuration - Docker compose

Using Docker Compose directly instead of using the `opik.sh` or `opik.ps1`
scripts provides you with some additional options.

### Starting Opik with Docker Compose

Instead of using the `opik.sh` or `opik.ps1` scripts, you can also run the
`docker compose` command directly with service profiles:

```bash
# Navigate to the opik/deployment/docker-compose directory
cd opik/deployment/docker-compose

# Start full Opik platform (equivalent to ./opik.sh)
docker compose --profile opik up --detach

# Start only infrastructure services (equivalent to ./opik.sh --infra)
docker compose up --detach

# Start infrastructure + backend services (equivalent to ./opik.sh --backend)
docker compose --profile backend up --detach
```

### Uninstalling Opik

To remove Opik, you can use the script or remove containers and volumes manually:

```bash
# Using the script (recommended)
./opik.sh --stop

# Or manually remove containers and volumes
cd deployment/docker-compose
docker compose --profile opik down --volumes
```

> **Warning**
>
> Removing the volumes will delete all the data stored in the Opik platform and cannot be recovered. We do not recommend
> this option unless you are sure that you will not need any of the data stored in the Opik platform.

### Running a specific version of Opik

You can run a specific version of Opik by setting the `OPIK_VERSION` environment
variable:

```bash
OPIK_VERSION=latest

./opik.sh
```

### Building the Opik platform from source

You can also build the Opik platform from source using the provided script:

```bash
# Clone the Opik repository
git clone https://github.com/comet-ml/opik.git

# Navigate to the opik directory
cd opik

# Build the Opik platform from source
./opik.sh --build
```

This will build the Frontend and Backend Docker images and start the Opik platform.

## Troubleshooting

If you get this error when running `docker compose`

```bash
java.lang.Throwable: Code: 139. DB::Exception: No macro 'shard' in config while processing substitutions in '/clickhouse/tables/{shard}/opik/automation_rule_evaluator_logs' at '20' or macro is not supported here. (NO_ELEMENTS_IN_CONFIG) (version 24.3.6.48 (official build))
```

Please make sure you get the latest files from `deployment/docker-compose` folder

> Debug, evaluate, and monitor your LLM applications, RAG systems, and agentic workflows with comprehensive tracing, automated evaluations, and production-ready dashboards.