When to Use `uv run` vs `uvx`

Tip

Quick Decision: Use uv run for project-related code that needs your dependencies. Use uvx for standalone tools that should run independently of your project.

  • uv run: Executes code within your project’s environment using project dependencies
  • uvx/uv tool run: Runs standalone tools in isolated environments, independent of your project

Note

uvx is an alias for uv tool run

When to Use uv run

Use uv run when working within a project context:

# Project scripts and applications
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 to Use uvx

Use uvx for standalone tools independent of your current project:

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

# Global development tools
uvx black --check .
uvx pip-audit

# Project initialization
uvx django-admin startproject mysite

Key Behavioral Differences

Environment Isolation

uv run uses your project’s dependencies:

# Uses requests version from pyproject.toml
uv run python -c "import requests; print(requests.__version__)"

uvx creates isolated environments:

# Uses latest requests, ignoring project constraints
uvx --from requests python -c "import requests; print(requests.__version__)"

Decision Framework

  1. Working on a specific project? → uv run
  2. Need access to project dependencies? → uv run
  3. Running a standalone utility? → uvx
  4. Want tool isolated from project? → uvx

Learn More

Last updated on
What's the difference between pip and uv?Why are there so many Python packaging tools?

Please submit corrections and feedback...