Skip to main content
UR-2.0 provides a user-friendly installation process — with just a few commands, users can complete the basic environment setup.
UR-2.0 also supports a modular dependency system that allows flexible installation of required components on demand, avoiding unnecessary dependencies.

​
Create a Virtual Environment with Conda

​
Step 1: Pre-installation Setup

Create a virtual environment using Conda: 
conda create -n ultrarag python=3.11
conda activate ultrarag
Don’t have Conda installed? Visit Install Miniconda.
We recommend using uv for package management — it provides a faster and more reliable Python dependency management experience: 
pip install uv

​
Step 2: Install the Base Environment

Clone the project from GitHub to your local machine or server: 
git clone https://github.com/OpenBMB/UltraRAG.git --depth 1
cd UltraRAG
Create a Conda virtual environment and install basic dependencies: 
uv pip install -e .

​
Step 3: Verify Installation

Run the following command to check whether the installation was successful: 
# Successful execution will display the welcome message 'Hello, UltraRAG 2.0!'
ultrarag run examples/sayhello.yaml
If everything is correctly configured, the terminal will display the welcome message:

​
Step 4: Install Optional Components

UR-2.0 supports a wide variety of Server components.
Developers can flexibly install only the dependencies required for their tasks: 
# Retriever/Reranker Server dependencies:
# infinity
uv pip install infinity_emb
# sentence_transformers
uv pip install sentence_transformers
# openai
uv pip install openai
# bm25
uv pip install bm25s
# faiss (requires manual installation of CPU or GPU version depending on your hardware)
# CPU version:
uv pip install faiss-cpu
# GPU version (example: CUDA 12.x)
uv pip install faiss-gpu-cu12
# For other CUDA versions, install the corresponding package (e.g., CUDA 11.x → faiss-gpu-cu11)
# websearch
# exa
uv pip install exa_py
# tavily
uv pip install tavily-python
# One-click installation:
uv pip install -e ".[retriever]"

# Generation Server dependencies:
# vllm
uv pip install vllm
# openai
uv pip install openai
# hf
uv pip install transformers
# One-click installation:
uv pip install -e ".[generation]"

# Corpus Server dependencies:
# chonkie
uv pip install chonkie
# pymupdf
uv pip install pymupdf
# mineru
uv pip install "mineru[core]"
# One-click installation:
uv pip install -e ".[corpus]"

# Install all dependencies:
uv pip install -e ".[all]"
# Or use Conda to import the environment:
conda env create -f environment.yml

​
Build and Run Environment with Docker

(Option 1) Clone the project to your local machine or server via git: 
git clone https://github.com/OpenBMB/UltraRAG.git --depth 1
cd UltraRAG
Build the image: 
docker build -t ultrarag:v0.2.1 .
Run an interactive environment: 
docker run -it --gpus all ultrarag:v0.2.1 /bin/bash
(Option 2) Use the Prebuilt Image Pull the prebuilt image: 
docker pull hdxin2002/ultrarag:v0.2.1
Run an interactive environment: 
docker run -it --gpus all hdxin2002/ultrarag:v0.2.1 /bin/bash
Run the following command to verify whether the installation is successful: 
# If successful, it will display the welcome message 'Hello, UltraRAG 2.0!'
ultrarag run examples/sayhello.yaml