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 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:

## Direct install
pip install uv
## Download script
curl -LsSf https://astral.sh/uv/install.sh | sh

Download Source Code

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:
uv sync
Full installation: If you want to fully experience UltraRAG’s retrieval, generation, corpus processing, and evaluation functions, please run:
uv sync --all-extras

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

uv sync --extra retriever   # Retrieval module only
uv sync --extra generation  # Generation module only

Once installed, activate the virtual environment:

# 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:

# 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

# 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

# Start the container (Port 5050 is mapped by default)
docker run -it --gpus all -p 5050:5050 <docker_image_name>

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

Verify Installation

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

ultrarag run examples/sayhello.yaml

Seeing the following output indicates a successful installation:

Hello, UltraRAG v3!

Get Started

RAG Servers

RAG Client

Develop Guide

Typical Implementation

Source Code Installation

Docker Container Deployment

Verify Installation

​Source Code Installation

​Docker Container Deployment

​Verify Installation

Source Code Installation

Docker Container Deployment

Verify Installation