Run a command provided by a Python package.

By default, the package to install is assumed to match the command name.

The name of the command can include an exact version in the format `<package>@<version>`, e.g., `uv tool run ruff@0.3.0`. If more complex version specification is desired or if the command is provided by a
different package, use `--from`.

`uvx` can be used to invoke Python, e.g., with `uvx python` or `uvx python@<version>`. A Python interpreter will be started in an isolated virtual environment.

If the tool was previously installed, i.e., via `uv tool install`, the installed version will be used unless a version is requested or the `--isolated` flag is used.

`uvx` is provided as a convenient alias for `uv tool run`, their behavior is identical.

If no command is provided, the installed tools are displayed.

Packages are installed into an ephemeral virtual environment in the uv cache directory.

Usage: uv tool run [OPTIONS] [COMMAND]

Options:
      --from <FROM>
          Use the given package to provide the command.
          
          By default, the package name is assumed to match the command name.

      --with <WITH>
          Run with the given packages installed

      --with-editable <WITH_EDITABLE>
          Run with the given packages installed in editable mode
          
          When used in a project, these dependencies will be layered on top of the uv tool's environment in a separate, ephemeral environment. These dependencies are allowed to conflict with those specified.

      --with-requirements <WITH_REQUIREMENTS>
          Run with all packages listed in the given `requirements.txt` files

      --isolated
          Run the tool in an isolated virtual environment, ignoring any already-installed tools

Index options:
      --index <INDEX>
          The URLs to use when resolving dependencies, in addition to the default index.
          
          Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.
          
          All indexes provided via this flag take priority over the index specified by `--default-index` (which defaults to PyPI). When multiple `--index` flags are provided, earlier values take priority.
          
          [env: UV_INDEX=]

      --default-index <DEFAULT_INDEX>
          The URL of the default package index (by default: <https://pypi.org/simple>).
          
          Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.
          
          The index given by this flag is given lower priority than all other indexes specified via the `--index` flag.
          
          [env: UV_DEFAULT_INDEX=]

  -i, --index-url <INDEX_URL>
          (Deprecated: use `--default-index` instead) The URL of the Python package index (by default: <https://pypi.org/simple>).
          
          Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.
          
          The index given by this flag is given lower priority than all other indexes specified via the `--extra-index-url` flag.
          
          [env: UV_INDEX_URL=]

      --extra-index-url <EXTRA_INDEX_URL>
          (Deprecated: use `--index` instead) Extra URLs of package indexes to use, in addition to `--index-url`.
          
          Accepts either a repository compliant with PEP 503 (the simple repository API), or a local directory laid out in the same format.
          
          All indexes provided via this flag take priority over the index specified by `--index-url` (which defaults to PyPI). When multiple `--extra-index-url` flags are provided, earlier values take priority.
          
          [env: UV_EXTRA_INDEX_URL=]

  -f, --find-links <FIND_LINKS>
          Locations to search for candidate distributions, in addition to those found in the registry indexes.
          
          If a path, the target must be a directory that contains packages as wheel files (`.whl`) or source distributions (e.g., `.tar.gz` or `.zip`) at the top level.
          
          If a URL, the page must contain a flat list of links to package files adhering to the formats described above.
          
          [env: UV_FIND_LINKS=]

      --no-index
          Ignore the registry index (e.g., PyPI), instead relying on direct URL dependencies and those provided via `--find-links`

      --index-strategy <INDEX_STRATEGY>
          The strategy to use when resolving against multiple index URLs.
          
          By default, uv will stop at the first index on which a given package is available, and limit resolutions to those present on that first index (`first-index`). This prevents "dependency confusion" attacks,
          whereby an attacker can upload a malicious package under the same name to an alternate index.
          
          [env: UV_INDEX_STRATEGY=]

          Possible values:
          - first-index:        Only use results from the first index that returns a match for a given package name
          - unsafe-first-match: Search for every package name across all indexes, exhausting the versions from the first index before moving on to the next
          - unsafe-best-match:  Search for every package name across all indexes, preferring the "best" version found. If a package version is in multiple indexes, only look at the entry for the first index

      --keyring-provider <KEYRING_PROVIDER>
          Attempt to use `keyring` for authentication for index URLs.
          
          At present, only `--keyring-provider subprocess` is supported, which configures uv to use the `keyring` CLI to handle authentication.
          
          Defaults to `disabled`.
          
          [env: UV_KEYRING_PROVIDER=]

          Possible values:
          - disabled:   Do not use keyring for credential lookup
          - subprocess: Use the `keyring` command for credential lookup

Resolver options:
  -U, --upgrade
          Allow package upgrades, ignoring pinned versions in any existing output file. Implies `--refresh`

  -P, --upgrade-package <UPGRADE_PACKAGE>
          Allow upgrades for a specific package, ignoring pinned versions in any existing output file. Implies `--refresh-package`

      --resolution <RESOLUTION>
          The strategy to use when selecting between the different compatible versions for a given package requirement.
          
          By default, uv will use the latest compatible version of each package (`highest`).
          
          [env: UV_RESOLUTION=]

          Possible values:
          - highest:       Resolve the highest compatible version of each package
          - lowest:        Resolve the lowest compatible version of each package
          - lowest-direct: Resolve the lowest compatible version of any direct dependencies, and the highest compatible version of any transitive dependencies

      --prerelease <PRERELEASE>
          The strategy to use when considering pre-release versions.
          
          By default, uv will accept pre-releases for packages that _only_ publish pre-releases, along with first-party requirements that contain an explicit pre-release marker in the declared specifiers
          (`if-necessary-or-explicit`).
          
          [env: UV_PRERELEASE=]

          Possible values:
          - disallow:                 Disallow all pre-release versions
          - allow:                    Allow all pre-release versions
          - if-necessary:             Allow pre-release versions if all versions of a package are pre-release
          - explicit:                 Allow pre-release versions for first-party packages with explicit pre-release markers in their version requirements
          - if-necessary-or-explicit: Allow pre-release versions if all versions of a package are pre-release, or if the package has an explicit pre-release marker in its version requirements

      --fork-strategy <FORK_STRATEGY>
          The strategy to use when selecting multiple versions of a given package across Python versions and platforms.
          
          By default, uv will optimize for selecting the latest version of each package for each supported Python version (`requires-python`), while minimizing the number of selected versions across platforms.
          
          Under `fewest`, uv will minimize the number of selected versions for each package, preferring older versions that are compatible with a wider range of supported Python versions or platforms.
          
          [env: UV_FORK_STRATEGY=]

          Possible values:
          - fewest:          Optimize for selecting the fewest number of versions for each package. Older versions may be preferred if they are compatible with a wider range of supported Python versions or
            platforms
          - requires-python: Optimize for selecting latest supported version of each package, for each supported Python version

      --exclude-newer <EXCLUDE_NEWER>
          Limit candidate packages to those that were uploaded prior to the given date.
          
          Accepts both RFC 3339 timestamps (e.g., `2006-12-02T02:07:43Z`) and local dates in the same format (e.g., `2006-12-02`) in your system's configured time zone.
          
          [env: UV_EXCLUDE_NEWER=]

      --no-sources
          Ignore the `tool.uv.sources` table when resolving dependencies. Used to lock against the standards-compliant, publishable package metadata, as opposed to using any workspace, Git, URL, or local path
          sources

Installer options:
      --reinstall
          Reinstall all packages, regardless of whether they're already installed. Implies `--refresh`

      --reinstall-package <REINSTALL_PACKAGE>
          Reinstall a specific package, regardless of whether it's already installed. Implies `--refresh-package`

      --link-mode <LINK_MODE>
          The method to use when installing packages from the global cache.
          
          Defaults to `clone` (also known as Copy-on-Write) on macOS, and `hardlink` on Linux and Windows.
          
          [env: UV_LINK_MODE=]

          Possible values:
          - clone:    Clone (i.e., copy-on-write) packages from the wheel into the `site-packages` directory
          - copy:     Copy packages from the wheel into the `site-packages` directory
          - hardlink: Hard link packages from the wheel into the `site-packages` directory
          - symlink:  Symbolically link packages from the wheel into the `site-packages` directory

      --compile-bytecode
          Compile Python files to bytecode after installation.
          
          By default, uv does not compile Python (`.py`) files to bytecode (`__pycache__/*.pyc`); instead, compilation is performed lazily the first time a module is imported. For use-cases in which start time is
          critical, such as CLI applications and Docker containers, this option can be enabled to trade longer installation times for faster start times.
          
          When enabled, uv will process the entire site-packages directory (including packages that are not being modified by the current operation) for consistency. Like pip, it will also ignore errors.
          
          [env: UV_COMPILE_BYTECODE=]

Build options:
  -C, --config-setting <CONFIG_SETTING>
          Settings to pass to the PEP 517 build backend, specified as `KEY=VALUE` pairs

      --no-build-isolation
          Disable isolation when building source distributions.
          
          Assumes that build dependencies specified by PEP 518 are already installed.
          
          [env: UV_NO_BUILD_ISOLATION=]

      --no-build-isolation-package <NO_BUILD_ISOLATION_PACKAGE>
          Disable isolation when building source distributions for a specific package.
          
          Assumes that the packages' build dependencies specified by PEP 518 are already installed.

      --no-build
          Don't build source distributions.
          
          When enabled, resolving will not run arbitrary Python code. The cached wheels of already-built source distributions will be reused, but operations that require building distributions will exit with an
          error.

      --no-build-package <NO_BUILD_PACKAGE>
          Don't build source distributions for a specific package

      --no-binary
          Don't install pre-built wheels.
          
          The given packages will be built and installed from source. The resolver will still use pre-built wheels to extract package metadata, if available.
          
          [env: UV_NO_BINARY=]

      --no-binary-package <NO_BINARY_PACKAGE>
          Don't install pre-built wheels for a specific package
          
          [env: UV_NO_BINARY_PACKAGE=]

Cache options:
  -n, --no-cache
          Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation
          
          [env: UV_NO_CACHE=]

      --cache-dir <CACHE_DIR>
          Path to the cache directory.
          
          Defaults to `$XDG_CACHE_HOME/uv` or `$HOME/.cache/uv` on macOS and Linux, and `%LOCALAPPDATA%\uv\cache` on Windows.
          
          To view the location of the cache directory, run `uv cache dir`.
          
          [env: UV_CACHE_DIR=]

      --refresh
          Refresh all cached data

      --refresh-package <REFRESH_PACKAGE>
          Refresh cached data for a specific package

Python options:
  -p, --python <PYTHON>
          The Python interpreter to use to build the run environment.
          
          See `uv help python` for details on Python discovery and supported request formats.
          
          [env: UV_PYTHON=]

      --python-preference <PYTHON_PREFERENCE>
          Whether to prefer uv-managed or system Python installations.
          
          By default, uv prefers using Python versions it manages. However, it will use system Python installations if a uv-managed Python is not installed. This option allows prioritizing or ignoring system Python
          installations.
          
          [env: UV_PYTHON_PREFERENCE=]

          Possible values:
          - only-managed: Only use managed Python installations; never use system Python installations
          - managed:      Prefer managed Python installations over system Python installations
          - system:       Prefer system Python installations over managed Python installations
          - only-system:  Only use system Python installations; never use managed Python installations

      --no-python-downloads
          Disable automatic downloads of Python. [env: "UV_PYTHON_DOWNLOADS=never"]

Global options:
  -q, --quiet
          Do not print any output

  -v, --verbose...
          Use verbose output.
          
          You can configure fine-grained logging using the `RUST_LOG` environment variable. (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)

      --color <COLOR_CHOICE>
          Control the use of color in output.
          
          By default, uv will automatically detect support for colors when writing to a terminal.

          Possible values:
          - auto:   Enables colored output only when the output is going to a terminal or TTY with support
          - always: Enables colored output regardless of the detected environment
          - never:  Disables colored output

      --native-tls
          Whether to load TLS certificates from the platform's native certificate store.
          
          By default, uv loads certificates from the bundled `webpki-roots` crate. The `webpki-roots` are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance
          (especially on macOS).
          
          However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's
          certificate store.
          
          [env: UV_NATIVE_TLS=]

      --offline
          Disable network access.
          
          When disabled, uv will only use locally cached data and locally available files.
          
          [env: UV_OFFLINE=]

      --allow-insecure-host <ALLOW_INSECURE_HOST>
          Allow insecure connections to a host.
          
          Can be provided multiple times.
          
          Expects to receive either a hostname (e.g., `localhost`), a host-port pair (e.g., `localhost:8080`), or a URL (e.g., `https://localhost`).
          
          WARNING: Hosts included in this list will not be verified against the system's certificate store. Only use `--allow-insecure-host` in a secure network with verified sources, as it bypasses SSL
          verification and could expose you to MITM attacks.
          
          [env: UV_INSECURE_HOST=]

      --no-progress
          Hide all progress outputs.
          
          For example, spinners or progress bars.
          
          [env: UV_NO_PROGRESS=]

      --directory <DIRECTORY>
          Change to the given directory prior to running the command.
          
          Relative paths are resolved with the given directory as the base.
          
          See `--project` to only change the project root directory.

      --project <PROJECT>
          Run the command within the given project directory.
          
          All `pyproject.toml`, `uv.toml`, and `.python-version` files will be discovered by walking up the directory tree from the project root, as will the project's virtual environment (`.venv`).
          
          Other command-line arguments (such as relative paths) will be resolved relative to the current working directory.
          
          See `--directory` to change the working directory entirely.
          
          This setting has no effect when used in the `uv pip` interface.

      --config-file <CONFIG_FILE>
          The path to a `uv.toml` file to use for configuration.
          
          While uv configuration can be included in a `pyproject.toml` file, it is not allowed in this context.
          
          [env: UV_CONFIG_FILE=]

      --no-config
          Avoid discovering configuration files (`pyproject.toml`, `uv.toml`).
          
          Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.
          
          [env: UV_NO_CONFIG=]

  -h, --help
          Display the concise help for this command

  -V, --version
          Display the uv version

