When to Use `uv run` vs `uvx`

Use uv run to execute code inside your project’s virtual environment with its locked dependencies. Use uvx to run a standalone tool in an environment that ignores your project’s dependencies: a cached temporary one, or the persistent one uv tool install created if the tool is already installed. uvx is shorthand for uv tool run.

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

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 builds a cached temporary environment when the tool is not already installed. After uv tool install ruff, plain uvx ruff reuses that persistent environment instead, so the version you get is the installed one until you ask for another with uvx ruff@latest. Use uv tool install to put a tool on your PATH as a lasting command.

Pick your next step

• Building a project? Create your first Python project uses uv run throughout.
• Writing a standalone script? Write a self-contained script with inline dependencies and uv run.
• Locking script dependencies? Lock uv script dependencies makes uv run reproducible for scripts.
• Choosing a project structure? Understanding uv init project types explains when uv run executes an entry point vs. a file.