# When to Use `uv run` vs `uvx`


`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](https://pydevtools.com/handbook/explanation/what-is-a-virtual-environment.md), with access to the exact package versions pinned in your lockfile:

```bash
# 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:

```bash
# 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

- [uv](https://pydevtools.com/handbook/reference/uv.md) reference
- [uvx](https://pydevtools.com/handbook/reference/uvx.md) reference
- [How to write self-contained Python scripts using PEP 723](https://pydevtools.com/handbook/how-to/how-to-write-a-self-contained-script.md) covers inline script metadata with `uv run`
- [How to install Python CLI tools without Python](https://pydevtools.com/handbook/how-to/how-to-install-python-cli-tools-without-python.md) covers `uvx` for tool installation
- [Using tools (uv documentation)](https://docs.astral.sh/uv/guides/tools/)