uv tool run

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

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 ruff@0.3.0.

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 ruff@0.3.0 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 python@3.11

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 cpython@3.12 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 ruff@0.3.0 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 ruff@0.2.0 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

• uv tool install - Install a tool for repeated use
• uv tool list - List installed tools
• uv tool uninstall - Uninstall a tool
• uv run - Run scripts in a project context