Upgrade OpenRAG

Use these steps to upgrade your OpenRAG deployment to the latest version or a specific version.

Export customized flows before upgrading

If you modified the built-in flows or created custom flows in your OpenRAG Langflow instance, export your flows before upgrading. This ensure that you won't lose your flows after upgrading, and you can reference the exported flows if there are any breaking changes in the new version.

Upgrade TUI-managed deployments

To upgrade OpenRAG, you need to upgrade the OpenRAG Python package, and then upgrade the OpenRAG containers.

Upgrading the Python package also upgrades Docling by bumping the dependency in pyproject.toml.

This is a two-part process because upgrading the OpenRAG Python package updates the Terminal User Interface (TUI) and Python code, but the container versions are controlled by environment variables in your OpenRAG .env file.

1. If you modified the built-in flows or created custom flows in your OpenRAG Langflow instance, export your flows before starting this process. Although OpenRAG can preserve changes to the built-in flows, it doesn't preserve user-created flows. As a general best practice, exporting your flows is recommended to create backups of your customizations. Afterwards, you can reimport your flows or reference the exported flow JSON as needed.

2. To check for updates, click Status in the TUI, and then click Upgrade.

3. If there is an update available, press Esc to close the Status page, then then click Stop All Services.

4. Press q to exit the TUI.

5. Upgrade the OpenRAG Python package to the latest version from PyPI. The commands to upgrade the package depend on how you installed OpenRAG.

   uvx

   Use these steps to upgrade the Python package if you installed OpenRAG using uvx:

   1. Navigate to your OpenRAG workspace directory:

      cd openrag-workspace

   2. Upgrade the OpenRAG package:

      uvx --from openrag openrag

      You can invoke a specific version using any of the uvx version specifiers, such as --from:

      uvx --from openrag==0.1.30 openrag

   uv add

   Use these steps to upgrade the Python package if you installed OpenRAG with uv add:

   1. Navigate to your project directory:

      cd YOUR_PROJECT_NAME

   2. Update OpenRAG to the latest version:

      uv add --upgrade openrag

      To upgrade to a specific version:

      uv add --upgrade openrag==0.1.33

   3. Start the OpenRAG TUI:

      uv run openrag

   uv pip install

   Use these steps to upgrade the Python package if you installed OpenRAG with uv pip install:

   1. Activate your virtual environment.

   2. Upgrade OpenRAG:

      uv pip install --upgrade openrag

      To upgrade to a specific version:

      uv pip install --upgrade openrag==0.1.33

   3. Start the OpenRAG TUI:

      uv run openrag

6. In the OpenRAG TUI, click Start Services, and then wait while the services start.

   When you start services, the TUI dictates the container version at runtime. It overrides the OPENRAG_VERSION variable in your .env file to match the currently installed OpenRAG Python package version.

   This ensures that your TUI and containers are always synchronized when using the TUI to manage services.

   tip

   If you want to use a specific container version different from your TUI version, you must use manual docker compose or make commands instead of the TUI, or you can downgrade your Python package version.

   If you get an error that langflow container already exists error during upgrade, see Langflow container already exists during upgrade.

7. After the containers start, click Close, and then click Launch OpenRAG.

Upgrade self-managed deployments

1. If you modified the built-in flows or created custom flows in your OpenRAG Langflow instance, export your flows before starting this process. Although OpenRAG can preserve changes to the built-in flows, it doesn't preserve user-created flows. As a general best practice, exporting your flows is recommended to create backups of your customizations. Afterwards, you can reimport your flows or reference the exported flow JSON as needed.

2. Fetch and apply the latest container images while preserving your OpenRAG data:

   Docker

   docker compose pull
   docker compose up -d --force-recreate

   Podman

   podman compose pull
   podman compose up -d --force-recreate

   By default, OpenRAG's docker-compose files pull the latest container images. However, you can pin the OPENRAG_VERSION in your .env file to a specific version tag.

   If you run OpenRAG using make commands or manual docker compose commands, the OPENRAG_VERSION variable is used exactly as defined in the .env file. This allows you to pin the deployment to a specific version when managing the services manually.

3. After the containers start, access the OpenRAG application at http://localhost:3000.

See also

• Manage OpenRAG services
• Troubleshoot OpenRAG