Skip to content

When to Use `uv run` vs `uvx`

by Tim Hopper · Markdown
uv

Use uv run to execute code inside your project’s virtual environment with its locked dependencies. Use uvx to run a standalone tool in a temporary, isolated environment that ignores your project’s dependencies. uvx is shorthand for uv tool run.

The question each answers: does the code belong to your project, or to a standalone tool?

uv run uvx (uv tool run)
Environment Your project’s .venv Temporary and isolated
Uses your project’s dependencies Yes No
Needs a project Yes No
Typical use pytest, flask run, project scripts ruff, cookiecutter, django-admin

When should you use uv run?

uv run executes code inside your project’s virtual environment, with access to the exact package versions pinned in your lockfile:

# Run scripts that import project code
uv run src/myproject/main.py
uv run python -c "import requests; print(requests.__version__)"

# Development workflows
uv run pytest tests/
uv run flask run
uv run python manage.py migrate

# Interactive sessions with project dependencies
uv run python
uv run ipython

When should you use uvx?

uvx runs a tool in its own isolated environment that does not share your project’s packages. The tool installs once, caches, and runs cleanly without touching your virtual environment:

# One-off tool execution
uvx ruff format .
uvx cookiecutter gh:user/template

# Code-quality utilities
uvx pip-audit
uvx pyupgrade --py312-plus some_file.py

# Project initialization (before a project exists)
uvx django-admin startproject mysite

This isolation matters when a tool’s dependencies would conflict with your project’s, or when you want to run something that isn’t listed in your project at all.

uvx runs the tool in a temporary environment each time. To install a tool as a persistent command on your PATH, use uv tool install instead.

Learn More

Last updated on
When should I choose pixi over uv?Which Python package manager should I use?