Skip to main content

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 ensures 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 terminal-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 OpenRAG terminal 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. Exporting your flows is recommended because it creates backups of your flow customizations. Afterwards, you can reimport your flows or reference the exported flow JSON as needed.

  1. To check for updates, you must start the terminal session with --tui, such as uv run openrag --tui.

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

    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

  6. In the OpenRAG terminal session, select the Start services option, and then wait while the services start.

    When you start services, OpenRAG dictates the container version at runtime. It automatically sets the OPENRAG_VERSION variable in your .env file to match the currently installed OpenRAG Python package version. This ensures that your terminal and containers are always synchronized when using an OpenRAG terminal session to manage services. If you want to use a specific container version that is different from your terminal version, you must use the self-managed deployment commands.

    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, select the Open OpenRAG in browser option if the app doesn't launch automatically.

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. Exporting your flows is recommended because it creates backups of your flow customizations. Afterwards, you can reimport your flows or reference the exported flow JSON as needed.

  1. 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. To use a specific earlier version, you set OPENRAG_VERSION in your .env file to the desired image tag, and then run OpenRAG with docker compose, podman compose, or make commands. Overriding the OPENRAG_VERSION is only possible with self-managed deployments. This allows you to pin your OpenRAG containers to a specific version rather than deploying the latest version.

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

See also​