Skip to content

When to Use `uv run` vs `uvx`

by Tim Hopper · Markdown
uv

uv run and uvx both execute code, but they answer a different question: does the code belong to your project, or to a standalone tool?

uvx is shorthand for uv tool run. Both names refer to the same command.

Use uv run inside a project

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

Use uvx for standalone tools

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.

Learn More

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