uv — Python Package & Project Manager

uv is a fast, all-in-one Python tool manager (replaces pip, pip-tools, pipx, pyenv, virtualenv). It is required by many OpenClaw skills that run Python scripts or install Python CLI tools.

Check if uv is installed

uv --version

---

Install uv (if not present)

macOS / Linux (recommended)

curl -LsSf https://astral.sh/uv/install.sh | sh

After install, reload PATH:

source ~/.bashrc 2>/dev/null || source ~/.zshrc 2>/dev/null || export PATH="$HOME/.cargo/bin:$PATH"

macOS via Homebrew

brew install uv

pip (if Python already available)

pip install uv

Windows (PowerShell)

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

Verify install:

uv --version

---

Install Python CLI Tools (uv tool install)

Use for tools that expose a command-line binary (nano-pdf, ruff, etc.):

# Install a tool globally (available system-wide)
uv tool install nano-pdf
uv tool install ruff
uv tool install httpie

# Install a specific version
uv tool install nano-pdf==0.3.1

# List installed tools
uv tool list

# Upgrade a tool
uv tool upgrade nano-pdf

# Uninstall a tool
uv tool uninstall nano-pdf

---

Install Packages (uv pip install)

Drop-in replacement for pip install, uses the active virtual environment:

# Install a package
uv pip install requests
uv pip install "python-pptx>=0.6.23"

# Install from requirements file
uv pip install -r requirements.txt

# Install current project in editable mode
uv pip install -e .

# Show installed package info
uv pip show requests

# List all installed packages
uv pip list

# Uninstall
uv pip uninstall requests

---

Run Scripts (uv run)

Run a Python script without manually activating a venv. Handles dependencies automatically:

# Run a script directly
uv run script.py

# Run with extra packages (inline, no venv needed)
uv run --with requests script.py
uv run --with "requests>=2.28" --with pillow script.py

# Run a module
uv run -m http.server 8080

# Run with a specific Python version
uv run --python 3.12 script.py

For scripts with inline dependency metadata (PEP 723):

# /// script
# requires-python = ">=3.11"
# dependencies = ["requests", "pillow"]
# ///
import requests
...

uv run script.py  # auto-installs requests and pillow

---

Manage Python Versions

# Install a specific Python version
uv python install 3.12
uv python install 3.11 3.12 3.13

# List installed Python versions
uv python list

# Pin Python version for current project
uv python pin 3.12

---

Virtual Environments

# Create a virtual environment
uv venv                    # creates .venv in current dir
uv venv myenv              # custom name
uv venv --python 3.12      # specific Python version

# Activate (standard shell activation)
source .venv/bin/activate   # macOS/Linux
.venv\Scripts\activate      # Windows

# Install packages into the venv
uv pip install requests

---

Project Management (uv sync / uv add)

For projects with pyproject.toml:

# Sync all dependencies from lockfile
uv sync

# Add a dependency
uv add requests
uv add "fastapi>=0.100"

# Add a dev dependency
uv add --dev pytest

# Remove a dependency
uv remove requests

# Lock without installing
uv lock

---

Common Patterns for OpenClaw Skills

Run a skill script with dependencies

uv run {skillDir}/scripts/my_script.py --arg value

Install a Python skill tool then run it

uv tool install nano-pdf
nano-pdf ...

Quick one-off script with packages

uv run --with httpx --with rich python3 -c "
import httpx, rich
r = httpx.get('https://api.github.com')
rich.print(r.json())
"

---

Troubleshooting

uv: command not found after install:

# Add uv to PATH manually
export PATH="$HOME/.cargo/bin:$PATH"          # curl install default location
export PATH="$HOME/.local/bin:$PATH"          # some Linux distros
# Then add to shell profile permanently:
echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.zshrc

uv tool install binary not found after install:

# uv tool binaries live in:
uv tool dir --bin   # shows the bin directory
# Ensure it's in PATH:
export PATH="$(uv tool dir --bin):$PATH"

Permission error on Linux:

# Run with user install (no sudo needed)
curl -LsSf https://astral.sh/uv/install.sh | sh
# uv always installs to user space (~/.cargo/bin), never needs sudo

Slow install / behind proxy:

UV_HTTP_TIMEOUT=120 uv tool install nano-pdf