Skip to content

When to Use `uv run` vs `uvx`

by Tim Hopper
uv

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__)"

Which One to Pick

  1. If you’re working on a specific project → uv run
  2. If you need access to project dependencies → uv run
  3. If you’re running a standalone utility → uvx
  4. If you want a tool isolated from your project → uvx

Related

Learn More

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

Please submit corrections and feedback...