> ## Documentation Index
> Fetch the complete documentation index at: https://ultrarag.openbmb.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

UltraRAG provides two installation methods: local source code installation (recommended using `uv` for package management) and Docker container deployment.

## Source Code Installation

We strongly recommend using [uv](https://github.com/astral-sh/uv) to manage the Python environment and dependencies, as it can greatly improve installation speed.

**Prepare Environment**

If you haven't installed uv yet, please execute:

```shell theme={null}
## Direct install
pip install uv
## Download script
curl -LsSf https://astral.sh/uv/install.sh | sh
```

**Download Source Code**

```shell theme={null}
git clone https://github.com/OpenBMB/UltraRAG.git --depth 1
cd UltraRAG
```

**Install Dependencies**

Choose one of the following modes to install dependencies based on your use case:

**A: Create a New Environment** Use `uv sync` to automatically create a virtual environment and synchronize dependencies:

* Core dependencies: If you only need to run basic core functions, such as only using UltraRAG UI:
  ```shell theme={null}
  uv sync
  ```

* Full installation: If you want to fully experience UltraRAG's retrieval, generation, corpus processing, and evaluation functions, please run:
  ```shell theme={null}
  uv sync --all-extras
  ```

* On-demand installation: If you only need to run specific modules, keep the corresponding `--extra` as needed, for example:

  ```shell theme={null}
  uv sync --extra retriever   # Retrieval module only
  uv sync --extra generation  # Generation module only
  ```

Once installed, activate the virtual environment:

```shell theme={null}
# Windows CMD
.venv\Scripts\activate.bat

# Windows Powershell
.venv\Scripts\Activate.ps1

# macOS / Linux
source .venv/bin/activate
```

**B: Install into an Existing Environment** To install UltraRAG into your currently active Python environment, use `uv pip`:

```shell theme={null}
# Core dependencies
uv pip install -e .

# Full installation
uv pip install -e ".[all]"

# On-demand installation
uv pip install -e ".[retriever]"
```

## Docker Container Deployment

If you prefer not to configure a local Python environment, you can deploy using Docker.

**Get Code and Images**

```shell theme={null}
# 1. Clone the repository
git clone https://github.com/OpenBMB/UltraRAG.git --depth 1
cd UltraRAG

# 2. Prepare the image (choose one)
# Option A: Pull from Docker Hub
docker pull hdxin2002/ultrarag:v0.3.0-base-cpu # Base version (CPU)
docker pull hdxin2002/ultrarag:v0.3.0-base-gpu # Base version (GPU)
docker pull hdxin2002/ultrarag:v0.3.0          # Full version (GPU)

# Option B: Build locally
docker build -t ultrarag:v0.3.0 .

# 3. Start container (port 5050 is automatically mapped)
docker run -it --gpus all -p 5050:5050 <docker_image_name>
```

**Start the Container**

```shell theme={null}
# Start the container (Port 5050 is mapped by default)
docker run -it --gpus all -p 5050:5050 <docker_image_name>
```

<Note>After the container starts, UltraRAG UI will run automatically. You can directly access `http://localhost:5050` in your browser to use it.</Note>

## Verify Installation

After installation is complete, run the following example command to check if the environment is normal:

```shell theme={null}
ultrarag run examples/sayhello.yaml
```

Seeing the following output indicates a successful installation:

```
Hello, UltraRAG v3!
```