Skip to main content

​
uv tool run

Run a command provided by a Python package in an isolated environment.

​
Aliases

  • uvx - Convenient shorthand for uv tool run

​
Usage

uv tool run [OPTIONS] [COMMAND]
uvx [OPTIONS] [COMMAND]

​
Description

By default, the package to install is assumed to match the command name. The command name can include an exact version in the format <package>@<version>, e.g., uv tool run [email protected]. If the tool was previously installed via uv tool install, the installed version will be used unless a version is requested or the --isolated flag is used. Packages are installed into an ephemeral virtual environment in the uv cache directory.
uvx is provided as a convenient alias for uv tool run. Their behavior is identical.

​
Examples

​
Run a tool with default version

uvx ruff check .

​
Run a specific version

uvx [email protected] check .

​
Run a tool from a different package

uv tool run --from black blackd

​
Run with additional dependencies

uvx --with pandas --with numpy ipython

​
Run Python in an isolated environment

uvx python
uvx [email protected]

​
Run with requirements file

uvx --with-requirements requirements.txt myapp

​
Options

​
Package Selection

​
--from
string
Use the given package to provide the command. By default, the package name is assumed to match the command name.
uv tool run --from black blackd
​
-w, --with
string
Run with the given packages installed. Can be specified multiple times.
uvx --with pandas --with numpy ipython
​
--with-editable
path
Run with the given packages installed in editable mode. When used in a project, these dependencies will be layered on top of the tool’s environment in a separate, ephemeral environment.
uv tool run --with-editable ./my-package myapp
​
--with-requirements
file
Run with the packages listed in the given files. Supports requirements.txt, .py files with inline metadata, and pylock.toml.
uvx --with-requirements requirements.txt myapp

​
Constraints

​
-c, --constraint
file
Constrain versions using the given requirements files. Constraints files only control the version of a requirement but don’t trigger installation.
uv tool run -c constraints.txt ruff
​
--override
file
Override versions using the given requirements files. Overrides force a specific version regardless of other requirements.
uv tool run --override overrides.txt myapp
​
--build-constraint
file
Constrain build dependencies using the given requirements files when building source distributions.
uv tool run --build-constraint build-constraints.txt myapp

​
Environment Options

​
--isolated
boolean
Run the tool in an isolated virtual environment, ignoring any already-installed tools.
uvx --isolated ruff check .
​
--env-file
file
Load environment variables from a .env file. Can be provided multiple times, with subsequent files overriding previous values.
uv tool run --env-file .env --env-file .env.local myapp
​
--no-env-file
boolean
Avoid reading environment variables from a .env file.
uvx --no-env-file myapp

​
Python Options

​
-p, --python
string
The Python interpreter to use to build the run environment.See uv help python for details on Python discovery and supported request formats.
uvx --python 3.11 myapp
uvx --python [email protected] myapp
​
--python-platform
string
The platform for which requirements should be installed. Represented as a “target triple” (e.g., x86_64-unknown-linux-gnu or aarch64-apple-darwin).
This option is for advanced use cases. When specified, uv will select wheels compatible with the target platform, which may not be compatible with the current platform.
uv tool run --python-platform aarch64-apple-darwin myapp

​
PyTorch Options

​
--torch-backend
string
The backend to use when fetching packages in the PyTorch ecosystem (e.g., cpu, cu126, or auto).
This option is in preview and may change in future releases.
uvx --torch-backend cu126 myapp

​
Git Options

​
--lfs
boolean
Whether to use Git LFS when adding a dependency from Git.
uv tool run --lfs --from git+https://example.com/repo.git myapp

​
Advanced Options

​
--show-resolution
boolean
Whether to show resolver and installer output from any environment modifications. By default, environment modifications are omitted but enabled under --verbose.
uvx --show-resolution myapp

​
Version Specification

You can specify package versions in several ways:

​
Exact version

uvx [email protected] check .

​
Version constraint with —from

uv tool run --from "ruff>=0.3.0,<0.4.0" ruff check .

​
Latest version (default)

uvx ruff check .

​
Extras Specification

Install packages with optional extras: 
# Single extra
uvx --from "myapp[dev]" myapp

# Multiple extras
uvx --from "myapp[dev,test]" myapp

​
Troubleshooting

​
Command not found

If a command isn’t found, ensure the package name matches the command or use --from: 
# Wrong - 'black' package doesn't provide 'blackd' by default in command name
uvx blackd

# Correct - specify the package explicitly
uv tool run --from black blackd

​
Version conflicts

If you encounter version conflicts, use --isolated to ignore existing installations: 
uvx --isolated [email protected] check .

​
Cache issues

If you experience cache-related problems, clear the cache: 
uv cache clean
uvx ruff check .

​
Environment not activating

Ensure you’re not inside an active virtual environment that might interfere: 
deactivate  # Exit any active environment
uvx myapp

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us