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 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 installations​

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, and you want to preserve those changes, then you must export your flows before starting this process. Afterwards, you can import your flows or reference the exported flow JSON as needed.

  1. To check for updates, open the TUI's Status menu (3), and then click Upgrade.

  2. If there is an update, stop all OpenRAG services. In the Status menu, click Stop Services.

  3. 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 the installer script or 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

  4. In the OpenRAG TUI, click Start All Services, and then wait while the upgraded containers start.

    When you start services after upgrading the Python package, OpenRAG runs docker compose pull to get the appropriate container images matching the version specified in your OpenRAG .env file. Then, it recreates the containers with the new images using docker compose up -d --force-recreate.

    Pin container versions

    In the OpenRAG .env file, the OPENRAG_VERSION environment variable is set to latest by default, which pulls the latest available container images. To pin a specific container image version, you can set OPENRAG_VERSION to the desired container image version, such as OPENRAG_VERSION=0.1.33.

    However, when you upgrade the Python package, OpenRAG automatically attempts to keep the OPENRAG_VERSION synchronized with the Python package version. You might need to edit the .env file after upgrading the Python package to enforce a different container version. The TUI warns you if it detects a version mismatch.

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

  5. Under Native Services, click Start to start the Docling service.

  6. When the upgrade process is complete, you can close the Status window and continue using OpenRAG.

Upgrade self-managed containers​

  1. If you modified the built-in flows or created custom flows in your OpenRAG Langflow instance, and you want to preserve those changes, then you must export your flows before starting this process. Afterwards, you can import 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.

See also​