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


Use [`uv run`](https://pydevtools.com/handbook/reference/uv.md) 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?

| | `uv run` | `uvx` (`uv tool run`) |
|---|---|---|
| Environment | Your project's `.venv` | Isolated: cached temporary, or an existing tool install |
| Uses your project's dependencies | Yes | No |
| Needs a project | No, but uses one when present | No |
| Typical use | [pytest](https://pydevtools.com/handbook/reference/pytest.md), flask run, project scripts | [ruff](https://pydevtools.com/handbook/reference/ruff.md), [cookiecutter](https://pydevtools.com/handbook/reference/cookiecutter.md), django-admin |

## When should you use `uv run`?

`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](https://pydevtools.com/handbook/explanation/what-is-a-lock-file.md):

```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](https://pydevtools.com/handbook/reference/pytest.md) 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:

```bash
# One-off tool execution
uvx [ruff](https://pydevtools.com/handbook/reference/ruff.md) format .
uvx [cookiecutter](https://pydevtools.com/handbook/reference/cookiecutter.md) 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](https://pydevtools.com/handbook/tutorial/create-your-first-python-project.md) uses `uv run` throughout.
- **Writing a standalone script?** [Write a self-contained script](https://pydevtools.com/handbook/how-to/how-to-write-a-self-contained-script.md) with inline dependencies and `uv run`.
- **Locking script dependencies?** [Lock uv script dependencies](https://pydevtools.com/handbook/how-to/how-to-lock-uv-script-dependencies.md) makes `uv run` reproducible for scripts.
- **Choosing a project structure?** [Understanding uv init project types](https://pydevtools.com/handbook/explanation/understanding-uv-init-project-types.md) explains when `uv run` executes an entry point vs. a file.