I needed to run a Python script with dependencies managed by uv. Here’s how.

Basic usage Link to heading

Run a script:

uv run script.py

This automatically uses the virtual environment and installed dependencies.

Run with arguments:

uv run script.py --input data.csv

Run a module:

uv run -m pytest

Tools Link to heading

Install a tool and run it:

uv tool run black .

Or install it permanently:

uv tool install black
black .

List installed tools:

uv tool list

When to use uv run vs activating the venv Link to heading

Using uv run is generally preferable. The only time activating the venv manually makes sense is when running many commands interactively and typing uv run each time gets tedious.

For scripts, CI, and anything automated: uv run. It’s explicit and doesn’t depend on shell state.

Is uv ready to replace pip/poetry? Link to heading

For me, yes. I’ve migrated all my projects. The benefits:

  • Speed - Installs are 10-100x faster than pip
  • Lockfiles - Reproducible installs by default
  • All-in-one - Replaces pip, pip-tools, virtualenv, pyenv
  • Just works - Fewer edge cases than poetry

The only rough edge: some older packages with complex build requirements occasionally fail. But that’s rare.

Further reading Link to heading