How to Install uv

uv is a fast Python package manager and tool runner that simplifies running OAA Runner integrations. This guide covers how to install uv if it’s not already present on your system.

Prerequisites

  • A command-line terminal

  • Internet access to download uv

Check if uv is Already Installed

Before installing uv, verify whether it’s already available on your system. This is important because uv may have been installed previously or come with your system setup.

Run this command:

uv --version

What to expect:

  • ✅ If uv is installed, you’ll see output like: uv 0.1.15 (version number may vary)

  • ❌ If uv is not installed, you’ll see: command not found: uv or 'uv' is not recognized

If uv is already installed: You can skip the installation steps and proceed directly to running integrations.

Installation Methods

Choose the installation method that works best for your operating system.

Windows (PowerShell)

For Windows users, use the PowerShell installer:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Verify installation:

Open a new PowerShell window and run:

uv --version

macOS (Homebrew)

If you have Homebrew installed, you can use it to install uv:

brew install uv

Verify installation:

uv --version

Other Installation Methods

PyPI (pip or pipx)

If you have Python and pip installed, you can install uv via PyPI:

# Using pip
pip install uv

# Or using pipx (recommended to isolate uv)
pipx install uv

Verify installation:

uv --version

Windows Package Manager (WinGet)

If you have WinGet installed on Windows:

winget install --id=astral-sh.uv -e

Verify installation:

uv --version

Docker

If you use Docker and want uv in a container:

docker run ghcr.io/astral-sh/uv --version

Additional Resources

For more installation methods and detailed instructions, visit the official uv installation documentation.

Verify uv Installation

After installing uv, verify that it’s working correctly:

uv --version

You should see output like:

uv 0.1.15

The version number may be different depending on when you installed it.

Troubleshooting

“command not found: uv” on macOS/Linux

If you just installed uv and still get “command not found”, you may need to open a new terminal window or reload your shell configuration:

# Reload shell configuration
source ~/.bashrc
# or
source ~/.zshrc

“uv is not recognized” on Windows

If you just installed uv on Windows and still get this error:

  1. Open a new PowerShell window (close and reopen PowerShell completely)

  2. Try running uv --version again

Multiple Python Versions

uv is independent of your Python version, but you should have at least one Python installation available. If you have multiple Python versions:

uv --python python3.9  # Specify which Python to use

Permission Denied on macOS/Linux

If you get “Permission denied” when running the installer:

chmod +x ~/.local/bin/uv

Next Steps

Once uv is installed and verified, you can:

  1. Run an integration: See how-to-run-integrations-locally.md

  2. Build a new integration: See how-to-add-a-rest-api-source.md

  3. Understand the config: See reference/what-is-an-oaa-config-file.html

Why Use uv?

uv provides several advantages for running OAA Runner integrations:

  • ⚡ Fast dependency resolution - Much faster than traditional pip

  • 🔒 Isolated environments - Dependencies don’t interfere with system Python

  • 🔄 Reproducible builds - Same dependencies every time you run

  • 📦 Built-in tool runner - Run tools without installing them globally

  • 🎯 Simple integration - Works seamlessly with OAA Runner via uv tool run --from oaa-runner

Common uv Commands

After installation, here are some useful uv commands:

# Check version
uv --version

# Get help
uv --help

# Run an OAA integration
uv tool run --from oaa-runner oaa app run --config=config.yaml --save-json

# Run with additional dependencies
uv tool run --with-requirements=requirements.txt --from oaa-runner \
  oaa app run --config=config.yaml --save-json

# Run a Python script
uv run script.py

Support

If you encounter issues with uv installation:

  1. Check the official uv documentation

  2. Review the uv GitHub repository

  3. Check for known issues on GitHub Issues