---
title: Install OpenRAG
slug: /install
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import PartialOnboarding from '@site/docs/_partial-onboarding.mdx'; 

[Install the OpenRAG Python wheel](#install-python-wheel), and then run the [OpenRAG Terminal User Interface(TUI)](#setup) 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, on any operating system.

![OpenRAG TUI Interface](@site/static/img/OpenRAG_TUI_2025-09-10T13_04_11_757637.svg)

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.

Once OpenRAG is running, use the TUI to monitor your application, control your containers, and retrieve logs.

If you prefer running Docker commands and manually editing `.env` files, see [Install with Docker](/get-started/docker).

## Prerequisites 

- Install [Python Version 3.10 to 3.13](https://www.python.org/downloads/release/python-3100/)
- Install [uv](https://docs.astral.sh/uv/getting-started/installation/)
- Install [Podman](https://podman.io/docs/installation) (recommended) or [Docker](https://docs.docker.com/get-docker/)
- Install [Docker Compose](https://docs.docker.com/compose/install/). If using Podman, use [podman-compose](https://docs.podman.io/en/latest/markdown/podman-compose.1.html) or alias Docker compose commands to Podman commands.
- Create an [OpenAI API key](https://platform.openai.com/api-keys). This key is **required** to start OpenRAG, but you can choose a different model provider during [Application Onboarding](#application-onboarding).
- Optional: Install GPU support with an NVIDIA GPU, [CUDA](https://docs.nvidia.com/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.

## Install the OpenRAG Python wheel {#install-python-wheel}

:::important
The `.whl` file is currently available as an internal download during public preview, and will be published to PyPI in a future release.
:::

The OpenRAG wheel installs the Terminal User Interface (TUI) for configuring and running OpenRAG.

1. Create a new project with a virtual environment using `uv init`.

   ```bash
   uv init YOUR_PROJECT_NAME
   cd YOUR_PROJECT_NAME
   ```

   The `(venv)` prompt doesn't change, but `uv` commands will automatically use the project's virtual environment.
   For more information on virtual environments, see the [uv documentation](https://docs.astral.sh/uv/pip/environments).

2. Add the local OpenRAG wheel to your project's virtual environment.

   ```bash
   uv add PATH/TO/openrag-VERSION-py3-none-any.whl
   ```
   Replace `PATH/TO/` and `VERSION` with the path and version of your downloaded OpenRAG `.whl` file.

   For example, if your `.whl` file is in the `~/Downloads` directory, the command is `uv add ~/Downloads/openrag-0.1.8-py3-none-any.whl`.

3. Ensure all dependencies are installed and updated in your virtual environment.
   ```bash
   uv sync
   ```

4. Start the OpenRAG TUI.
   ```bash
   uv run openrag
   ```

5. Continue with [Set up OpenRAG with the TUI](#setup).

## Set up OpenRAG with the TUI {#setup}

The TUI creates a `.env` file in your OpenRAG directory root and starts OpenRAG.
If the TUI detects a `.env` file in the OpenRAG root directory, it sources any variables from the `.env` file.
If the TUI detects OAuth credentials, it enforces the **Advanced Setup** path.

<Tabs groupId="Setup method">
  <TabItem value="Basic setup" label="Basic setup" default>

    **Basic Setup** generates all of the required values for OpenRAG except the OpenAI API key.
    **Basic Setup** does not set up OAuth connections for ingestion from cloud providers.
    For OAuth setup, use **Advanced Setup**.
    For information about the difference between basic (no auth) and OAuth in OpenRAG, see [Authentication and document access](/knowledge#auth).

   1. To install OpenRAG with **Basic Setup**, click **Basic Setup** or press <kbd>1</kbd>. 
   2. Click **Generate Passwords** to generate passwords for OpenSearch and Langflow.
   3. Paste your OpenAI API key in the OpenAI API key field.
   4. Click **Save Configuration**.
   Your passwords are saved in the `.env` file used to start OpenRAG.
   5. To start OpenRAG, click **Start Container Services**.
      Startup pulls container images and runs them, so it can take some time.
      When startup is complete, the TUI displays the following:
      ```bash
      Services started successfully
      Command completed successfully
      ```
   6. To open the OpenRAG application, click **Open App**.
   7. Continue with [Application Onboarding](#application-onboarding).
  </TabItem>
  <TabItem value="Advanced setup" label="Advanced setup">

   1. To install OpenRAG with **Advanced Setup**, click **Advanced Setup** or press <kbd>2</kbd>. 
   2. Click **Generate Passwords** to generate passwords for OpenSearch and Langflow.
   3. Paste your OpenAI API key in the OpenAI API key field.
   4. Add your client and secret values for Google or Microsoft OAuth.
   These values can be found with your OAuth provider.
   For more information, see the [Google OAuth client](https://developers.google.com/identity/protocols/oauth2) or [Microsoft Graph OAuth client](https://learn.microsoft.com/en-us/onedrive/developer/rest-api/getting-started/graph-oauth) documentation.
   5. The OpenRAG TUI presents redirect URIs for your OAuth app.
   These are the URLs your OAuth provider will redirect back to after user sign-in.
   Register these redirect values with your OAuth provider as they are presented in the TUI.
   6. Click **Save Configuration**.
   7. To start OpenRAG, click **Start Container Services**.
      Startup pulls container images and runs them, so it can take some time.
      When startup is complete, the TUI displays the following:
      ```bash
      Services started successfully
      Command completed successfully
      ```
   8. To open the OpenRAG application, click **Open App**, press <kbd>6</kbd>, or navigate to `http://localhost:3000`.
   You are presented with your provider's OAuth sign-in screen.
   After sign-in, you are redirected to the redirect URI.

       Two additional variables are available for Advanced Setup:

       The `LANGFLOW_PUBLIC_URL` controls where the Langflow web interface can be accessed. This is where users interact with their flows in a browser.

       The `WEBHOOK_BASE_URL` controls where the endpoint for `/connectors/CONNECTOR_TYPE/webhook` will be available.
       This connection enables real-time document synchronization with external services.
       Supported webhook endpoints:
       - Google Drive: `/connectors/google_drive/webhook`
       - OneDrive: `/connectors/onedrive/webhook`  
       - SharePoint: `/connectors/sharepoint/webhook`
       
   9. Continue with [Application Onboarding](#application-onboarding).
  </TabItem>
</Tabs>

<PartialOnboarding />

## Manage OpenRAG containers with the TUI

After installation, the TUI can deploy, manage, and upgrade your OpenRAG containers.

### Start container services

Click **Start Container Services** to start the OpenRAG containers.
The TUI automatically detects your container runtime, and then checks if your machine has compatible GPU support by checking for `CUDA`, `NVIDIA_SMI`, and Docker/Podman runtime support. This check determines which Docker Compose file OpenRAG uses.
The TUI then pulls the images and deploys the containers with the following command.
```bash
docker compose up -d
```

If images are missing, the TUI runs `docker compose pull`, then runs `docker compose up -d`.

### Start native services

A "native" service in OpenRAG refers to a service run natively on your machine, and not within a container.
The `docling serve` process is a native service in OpenRAG, because it's a document processing service that is run on your local machine, and controlled separately from the containers.

To start or stop `docling serve` or any other native services, in the TUI main menu, click **Start Native Services** or **Stop Native Services**.

To view the status, port, or PID of a native service, in the TUI main menu, click [Status](#status).

### Status

The **Status** menu displays information on your container deployment.
Here you can check container health, find your service ports, view logs, and upgrade your containers.

To view streaming logs, select the container you want to view, and press <kbd>l</kbd>.
To copy your logs, click **Copy to Clipboard**.

To **upgrade** your containers, click **Upgrade**.
**Upgrade** runs `docker compose pull` and then `docker compose up -d --force-recreate`.
The first command pulls the latest images of OpenRAG.
The second command recreates the containers with your data persisted.

To **reset** your containers, click **Reset**.
Reset gives you a completely fresh start.
Reset deletes all of your data, including OpenSearch data, uploaded documents, and authentication.
**Reset** runs two commands.
It first stops and removes all containers, volumes, and local images.
```
docker compose down --volumes --remove-orphans --rmi local
```

When the first command is complete, OpenRAG removes any additional Docker objects with `prune`.

```
docker system prune -f
```

## Diagnostics

The **Diagnostics** menu provides health monitoring for your container runtimes and monitoring of your OpenSearch security.