Skip to main content

Install OpenRAG in a Python project with uv

Use uv 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) to configure and manage your OpenRAG deployment.

For other installation methods, see Select an installation method.

Prerequisites​

  • Install Python version 3.12 or later.
  • Install uv.

  • Install Podman or Docker.

    The OpenRAG team recommends, at minimum, 8 GB of RAM for container VMs. However, if you plan to upload large files regularly, more RAM is recommended. For more information, see Troubleshoot OpenRAG.

    A Docker or Podman VM must be running before you start OpenRAG.

  • Install podman-compose or Docker Compose. To use Docker Compose with Podman, you must alias Docker Compose commands to Podman commands.

  • Gather the credentials and connection details for one or more supported model providers:

    • OpenAI: Create an OpenAI API key.
    • Anthropic: Create an Anthropic API key. Anthropic provides language models only; you must select an additional provider for embeddings.
    • IBM watsonx.ai: Get your watsonx.ai API endpoint, IBM project ID, and IBM API key from your watsonx deployment.
    • Ollama: Deploy an Ollama instance and models locally, in the cloud, or on a remote server. Then, get your Ollama server's base URL and the names of the models that you want to use.

    OpenRAG requires at least one language model and one embedding model. If a provider offers both types of models, then you can use the same provider for both models. If a provider offers only one type, then you must configure two providers.

    Language models must support tool calling to be compatible with OpenRAG.

    For more information, see Complete the application onboarding process.

  • Optional: Install GPU support with an NVIDIA GPU, CUDA support, and compatible NVIDIA drivers on the OpenRAG host machine. If you don't have GPU capabilities, OpenRAG provides an alternate CPU-only deployment that is suitable for most use cases. The default CPU-only deployment doesn't prevent you from using GPU acceleration in external services, such as Ollama servers.

Install and start OpenRAG with uv​

There are two ways to install OpenRAG with uv:

  • uv add (Recommended): 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: Use the uv pip interface 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.

Use uv add​

  1. Create a new uv-managed Python project:

    uv init PROJECT_NAME --python 3.12

    The --python flag ensures that your project uses the minimum required Python version for OpenRAG. You can use a later Python version, if you prefer. Or, you can omit this flag if your system's default Python version is 3.12 or later.

  2. Change into your new project directory:

    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:

      uv add openrag

    • Add a specific version:

      uv add openrag==0.1.30

    • Add a local wheel:

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

    For more options, see Managing dependencies with uv.

  4. Optional: If you want to use a pre-populated OpenRAG .env file, create one at ~/.openrag/tui before starting OpenRAG.

  5. Start the OpenRAG TUI:

    uv run openrag

Use uv pip install​

  1. Activate your virtual environment.

  2. Install the OpenRAG Python package:

    uv pip install openrag

  3. Optional: If you want to use a pre-populated OpenRAG .env file, create one at ~/.openrag/tui before starting OpenRAG.

  4. Start the OpenRAG TUI:

    uv run openrag

Set up OpenRAG with the TUI​

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

  1. In the TUI, click either Basic Setup or Advanced Setup.

    info

    You must use Advanced Setup if you want to enable either OAuth mode or cloud storage connectors during initial set up:

    • OAuth mode: Controls document ownership and access in your OpenRAG OpenSearch knowledge base. Without OAuth mode, there is no differentiation between users; all users that access your OpenRAG instance can access and manage all uploaded documents.
    • Cloud storage connectors: Enables ingestion of documents from external storage services.

    If OpenRAG detects OAuth or cloud storage connector credentials during setup, it recommends Advanced Setup in the TUI.

    You can also enable these features later.

  2. Enter administrator passwords for the OpenRAG OpenSearch and Langflow services.

    The OpenSearch password is required, and a secure password is automatically generated if you don't provide one manually.

    The Langflow password is recommended but optional. If the Langflow password is empty, the Langflow server starts without authentication enabled. For more information, see Langflow settings.

    You can click Generate Password to create a Langflow password and username automatically.

  3. Optional: Under API Keys, enter your model provider credentials, or leave these fields empty if you want to configure model provider credentials during the application onboarding process.

    There is no material difference between providing these values now or during the application onboarding process. If you provide a credential now, it can be populated automatically during the application onboarding process if you enable the Use environment API key option.

    OpenRAG's core functionality requires access to language and embedding models. By default, OpenRAG uses OpenAI models. If you aren't sure which models or providers to use, you must provide an OpenAI API key to use OpenRAG's default model configuration.

  4. Advanced Setup only: To enable OAuth mode or cloud storage connectors, do the following:

    1. Register OpenRAG as an OAuth application in your cloud provider, and then obtain the app's OAuth credentials, such as a client ID and secret key. To enable multiple connectors, you must register an app and generate credentials for each provider.

    2. Enter the relevant OAuth credentials under API Keys in the TUI's Advanced Setup:

      The credentials can be populated automatically if OpenRAG detects these credentials in an OpenRAG .env file at ~/.openrag/tui.

    3. Register the redirect URIs shown in the TUI in your OAuth apps.

      The redirect URIs are used for the cloud storage connector webhooks. For Google, the redirect URIs are also used to redirect users back to OpenRAG after they sign in.

  5. Optional: Under Langfuse (Tracing), enter Langfuse credentials to enable the Langflow integration with Langfuse:

    • Langfuse Secret Key: A secret key for your Langfuse project.
    • Langfuse Public Key: A public key for your Langfuse project.
    • Langfuse Host: Required for self-hosted Langfuse deployments. Leave empty for Langfuse Cloud.

  6. Optional: Under Others, you can edit the following settings if needed:

    • Documents Paths: Set the local documents path. Use the default path, or provide a path to a directory where you want OpenRAG to look for documents to ingest into your knowledge base.
    • OpenSearch Data Path: Use the default path, or specify the path where you want OpenRAG to create your OpenSearch index.
    • Langflow Public URL (Advanced Setup only) : Sets the base address to access the Langflow web interface where users interact with the Langflow editor in a browser. You must set this value to run Langflow on a non-default port (7860)
    • Webhook Base URL (Advanced Setup only): If you entered OAuth credentials, you can set the base address for your OAuth connector endpoints. If set, the OAuth connector webhook URLs are constructed as WEBHOOK_BASE_URL/connectors/${provider}/webhook. This option is required to enable automatic ingestion from cloud storage.

  7. Click Save Configuration.

    Your passwords, API key, and OAuth credentials (if provided) are stored in the OpenRAG .env file at ~/.openrag/tui. If you modified any credentials that were pulled from an existing .env file, those values are updated in the .env file.

  8. Click Start OpenRAG to start the OpenRAG services.

    This process can take some time while OpenRAG pulls and runs the container images. If all services start successfully, the TUI prints a confirmation message:

    Services started successfully
    Command completed successfully

  9. Click Close, and then click Launch OpenRAG or navigate to localhost:3000 in your browser.

    If you provided Google OAuth credentials, you must sign in with Google before you are redirected to your OpenRAG instance.

  10. Continue with the application onboarding process.

Complete the application onboarding process​

The first time you start the OpenRAG application, you must complete the application onboarding process to select language and embedding models that are essential for OpenRAG features like the Chat.

To complete onboarding, you must configure at least one language model and one embedding model.

You can use different providers for your language model and embedding model, such as Anthropic for the language model and OpenAI for the embedding model. Additionally, you can select multiple embedding models.

info

Anthropic doesn't provide embedding models. If you select Anthropic for your language model, you must select a different provider for the embedding model.

  1. Enter your Anthropic API key, or enable Use environment API key to pull the key from your OpenRAG .env file.

  2. Under Advanced settings, select the language model that you want to use.

    Language models must support tool calling to be compatible with OpenRAG. Incompatible models aren't listed.

  3. Click Complete.

  4. Select a provider for embeddings, provide the required information, and then select the embedding model you want to use. For information about another provider's credentials and settings, see the instructions for that provider.

  5. Click Complete.

    After you configure the embedding model, OpenRAG uses your credentials and models to ingest some initial documents. This tests the connection, and it allows you to ask OpenRAG about itself in the Chat. If there is a problem with the model configuration, an error occurs and you are redirected back to the application onboarding screen. Verify that the credential is valid and has access to the selected model, and then click Complete to retry ingestion.

  6. Continue through the overview slides for a brief introduction to OpenRAG, or click Skip overview. The overview demonstrates some basic functionality that is covered in the quickstart and in other parts of the OpenRAG documentation.

Next steps​