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

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

```bash
# 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:
```bash
# Uses requests version from pyproject.toml
uv run python -c "import requests; print(requests.__version__)"
```

`uvx` creates isolated environments:
```bash
# 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

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

## Learn More

* [Using tools (uv documentation)](https://docs.astral.sh/uv/guides/tools/)