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.

Run project code with 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

Run standalone tools with uvx

uvx runs a tool in its own isolated environment that does not share your project’s packages. uv caches the tool environment for later runs:

# 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

Use this isolation when a tool’s dependencies conflict with your project’s, or when the tool is not a project dependency.

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.