Skip to content

Installation Guide

Installing from source

Info

Instead of installing from source, you may try pip install owa, following Install from PyPI guide, but note that this section is experimental.

Minimal Installation Guide

If you do not require efficient screen capture with owa-env-gst, installation is simple as:

$ git clone https://github.com/open-world-agents/open-world-agents
$ cd open-world-agents # Ensure you're at project root

$ uv sync --inexact

$ git clone https://github.com/open-world-agents/open-world-agents
$ cd open-world-agents # Ensure you're at project root

# Install core first
$ pip install -e projects/owa-core

# Install supporting packages
$ pip install -e projects/mcap-owa-support
$ pip install -e projects/owa-desktop
$ pip install -e projects/owa-env-gst

# Install CLI
$ pip install -e projects/owa-cli

Tip

When using pip instead of uv, the installation order matters because pip can't recognize [tool.uv.sources] in pyproject.toml.

Tip

open-world-agents is a mono-repo which is composed with multiple sub-repository and most sub-repositories are pip-installable python package in itself.

Only owa-env-gst, which utilizes GStreamer to efficiently capture screen deal with media processing, requires installing gstreamer by conda.

If you are on Windows OS and require screen capture on the device, follow Full Installation Guide instead.

Full Installation Guide

If you do require efficient screen capture with owa-env-gst, follow this guide.

Setup Virtual Environment (1/3)

Before installation, we recommend setting up a virtual environment.

  1. Follow the miniforge installation guide to install conda and mamba. mamba is just a faster conda. If you've already installed conda, you may skip this step.

  2. Create & activate your virtual environment: 

    $ conda create -n owa python=3.11 -y
$ conda activate owa

  3. (Optional) For Windows users who need desktop recorder: 

    $ mamba env update --name owa --file projects/owa-env-gst/environment.yml

Tip

You can use other virtual environment tools, but to fully utilize owa-env-gst, you must install GStreamer with conda/mamba.

Note: GStreamer is only needed if you plan to capture screens.

Setup uv (2/3)

We recommend setting up uv next:

  1. Follow the uv installation guide or simply run pip install uv in your activated environment.

  2. Install virtual-uv package: 

    $ pip install virtual-uv

Tip

Always activate your virtual environment before running any vuv commands.

Installation (3/3)

After all setup, installation is simple as:

$ git clone https://github.com/open-world-agents/open-world-agents
$ cd open-world-agents # Ensure you're at project root

$ vuv install

Tip

Always activate your virtual environment before running any vuv commands.

Install from PyPI & conda-forge (experimental)

Installation is simple as:

$ uv pip install owa

$ pip install owa

There're several packages related to open-world-agents.

  • PyPI packages:

    • owa-core: Contains only the core logic to manage OWA's EnvPlugin
    • owa: Contains several base EnvPlugins along with owa-core (requires separate GStreamer installation)
    • Note that we're adopting lockstep versioning, which provides same version for each first-party sub-projects. e.g. following version specification is valid: 
      pip install owa-core==0.3.2 owa-cli==0.3.2 owa-env-desktop==0.3.2

  • Conda packages (Coming soon):

    • owa: Complete package including all dependencies (GStreamer bundled)
    • The conda package will eliminate the need to install GStreamer separately
    • In the future, users will be able to simply run conda install -c conda-forge owa to get a fully functional installation
    • Note: This implementation is still in progress and not yet available