---
title: Install OpenRAG in a Python project with uv
slug: /install-uv
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import PartialOnboarding from '@site/docs/_partial-onboarding.mdx';
import PartialSetup from '@site/docs/_partial-setup.mdx';
import PartialPrereqCommon from '@site/docs/_partial-prereq-common.mdx';
import PartialPrereqNoScript from '@site/docs/_partial-prereq-no-script.mdx';
import PartialPrereqWindows from '@site/docs/_partial-prereq-windows.mdx';
import PartialPrereqPython from '@site/docs/_partial-prereq-python.mdx';
import PartialInstallNextSteps from '@site/docs/_partial-install-next-steps.mdx';
import PartialOpenSearchAuthMode from '@site/docs/_partial-opensearch-auth-mode.mdx';
import PartialOllamaModels from '@site/docs/_partial-ollama-models.mdx';

Use [`uv`](https://docs.astral.sh/uv/getting-started/installation/) to install OpenRAG as a managed or unmanaged dependency in a new or existing Python project.

When you install OpenRAG with `uv`, you will use the [Terminal User Interface (TUI)](/tui) to configure and manage your OpenRAG deployment.

For other installation methods, see [Select an installation method](/install-options).

## Prerequisites

<PartialPrereqWindows />

<PartialPrereqPython />

<PartialPrereqNoScript />

<PartialPrereqCommon />

## Install and start OpenRAG with uv

There are two ways to install OpenRAG with `uv`:

* [**`uv add`** (Recommended)](#uv-add): Install OpenRAG as a managed dependency in a new or existing `uv` Python project.
This is recommended because it adds OpenRAG to your `pyproject.toml` and lockfile for better management of dependencies and the virtual environment.

* [**`uv pip install`**](#uv-pip-install): Use the [`uv pip` interface](https://docs.astral.sh/uv/pip/) to install OpenRAG into an existing Python project that uses `pip`, `pip-tools`, and `virtualenv` commands.

If you encounter errors during installation, see [Troubleshoot OpenRAG](/support/troubleshoot).

### Use uv add {#uv-add}

1. Create a new `uv`-managed Python project:

   ```bash
   uv init PROJECT_NAME
   ```

2. Change into your new project directory:

   ```bash
   cd PROJECT_NAME
   ```

   Because `uv` manages the virtual environment for you, you won't see a `(venv)` prompt.
   `uv` commands automatically use the project's virtual environment.

3. Add OpenRAG to your project:

   * Add the latest version:

      ```bash
      uv add openrag
      ```

   * Add a specific version:

      ```bash
      uv add openrag==0.1.30
      ```

   * Add a local wheel:

      ```bash
      uv add path/to/openrag-VERSION-py3-none-any.whl
      ```

   For more options, see [Managing dependencies with `uv`](https://docs.astral.sh/uv/concepts/projects/dependencies/).

4. Optional: If you want to use a pre-populated [OpenRAG `.env` file](/reference/configuration), create one at `~/.openrag/tui` before starting OpenRAG.

5. Start the OpenRAG TUI:

   ```bash
   uv run openrag
   ```

### Use uv pip install {#uv-pip-install}

1. Activate your virtual environment.

2. Install the OpenRAG Python package:

   ```bash
   uv pip install openrag
   ```

3. Optional: If you want to use a pre-populated [OpenRAG `.env` file](/reference/configuration), create one at `~/.openrag/tui` before starting OpenRAG.

4. Start the OpenRAG TUI:

   ```bash
   uv run openrag
   ```

## Set up OpenRAG with the TUI {#setup}

When you install OpenRAG with `uv`, you manage the OpenRAG services with the TUI.
The TUI guides you through the initial configuration process before you start the OpenRAG services.

Your configuration values are stored in an [OpenRAG `.env` file](/reference/configuration) that is created automatically at `~/.openrag/tui`.
If OpenRAG detects an existing `.env` file in this directory, then the TUI can populate those values automatically during setup and onboarding.

Container definitions are stored in the `docker-compose` files in the same directory as the OpenRAG `.env` file.

<PartialSetup />

<PartialOnboarding />

<PartialInstallNextSteps />