Install OpenRAG with TUI
Install the OpenRAG Python wheel, and then run the OpenRAG Terminal User Interface(TUI) to start your OpenRAG deployment with a guided setup process.
+Install OpenRAG with TUI
Install OpenRAG and then run the OpenRAG Terminal User Interface(TUI) to start your OpenRAG deployment with a guided setup process.
The OpenRAG Terminal User Interface (TUI) allows you to set up, configure, and monitor your OpenRAG deployment directly from the terminal.
Instead of starting OpenRAG using Docker commands and manually editing values in the .env file, the TUI walks you through the setup. It prompts for variables where required, creates a .env file for you, and then starts OpenRAG.
Install OpenRAG
To use OpenRAG on Windows, use WSL (Windows Subsystem for Linux).
Install the OpenRAG Python wheel
-The OpenRAG wheel installs the Terminal User Interface (TUI) for configuring and running OpenRAG.
-To quickly install and start OpenRAG, run uvx openrag.
To first set up a project and then install OpenRAG, do the following:
+To set up a project and install OpenRAG as a dependency, do the following:
-
Create a new project with a virtual environment using
@@ -39,14 +37,15 @@ For more information on virtual environments, see the uv documentation.uv init. -
-
Ensure all dependencies are installed and updated in your virtual environment.
-+uv syncAdd OpenRAG to your project.
++uv add openragTo add a specific version of OpenRAG:
+uv add openrag==0.1.25 -
-
Install and start the OpenRAG TUI.
--uvx openragTo install a specific version of the Langflow package, add the required version to the command, such as
-uvx --from openrag==0.1.25 openrag.Install a local wheel without uvx
If you downloaded the OpenRAG wheel to your local machine, follow these steps:
-
+
-
Add the wheel to your project's virtual environment.
@@ -220,7 +219,7 @@ Theuv add PATH/TO/openrag-VERSION-py3-none-any.whldocling serveprocess is a native service in OpenRAG, because iTo start or stop
docling serveor any other native services, in the TUI Status menu, click Stop or Restart.To view the status, port, or PID of a native service, in the TUI main menu, click Status.
Diagnostics
-The Diagnostics menu provides health monitoring for your container runtimes and monitoring of your OpenSearch security.
Start the OpenRAG TUI.
++uv run openragInstall a local wheel
If you downloaded the OpenRAG wheel to your local machine, follow these steps:
-
podman machine stop
podman machine rm
podman machine init --memory 8192 # 8 GB example
podman machine start
Port conflicts
Ensure ports 3000, 7860, 8000, 9200, 5601 are available.
+OCR ingestion fails (easyocr not installed)
+If Docling ingestion fails with an OCR-related error and mentions easyocr is missing, this is likely due to a stale uv cache.
easyocr is already included as a dependency in OpenRAG's pyproject.toml. Project-managed installations using uv sync and uv run always sync dependencies directly from your pyproject.toml, so they should have easyocr installed.
If you're running OpenRAG with uvx openrag, uvx creates a cached, ephemeral environment that doesn't modify your project. This cache may become stale.
On macOS, this cache directory is typically a user cache directory such as /Users/USER_NAME/.cache/uv.
-
+
- To clear the uv cache, run:
++
uv cache clean
+ - Start OpenRAG:
++
uvx openrag
+
If you do not need OCR, you can disable OCR-based processing in your ingestion settings to avoid requiring easyocr.
Langflow container already exists
If you are running other versions of Langflow containers on your machine, you may encounter an issue where Docker or Podman thinks Langflow is already up.
Remove just the problem container, or clean up all containers and start fresh.
@@ -44,7 +58,7 @@ This example increases the machine size to 8 GB of RAM, which should be sufficie When the Close button is active, the upgrade is complete. Close the window and open the OpenRAG appplication. -