[{'Text': "Skip to content                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             \n\n# Tools\n\nTools are Python packages that provide command-line interfaces.\n\nNote\n\nSee the tools guide for an introduction to working with the tools interface — this document discusses details of tool management.\n\n## The `uv tool` interface\n\nuv includes a dedicated interface for interacting with tools. Tools can be invoked without installation using `uv tool run`, in which case their dependencies are installed in a temporary virtual environment isolated from the current project.\n\nBecause it is very common to run tools without installing them, a `uvx` alias is provided for `uv tool run` — the two commands are exactly equivalent. For brevity, the documentation will mostly refer to `uvx` instead of `uv tool run`.\n\nTools can also be installed with `uv tool install`, in which case their executables are available on the `PATH` — an isolated virtual environment is still used, but it is not removed when the command completes.\n\n## Execution vs installation\n\nIn most cases, executing a tool with `uvx` is more appropriate than installing the tool. Installing the tool is useful if you need the tool to be available to other programs on your system, e.g., if some script you do not control requires the tool, or if you are in a Docker image and want to make the tool available to users.\n\n## Tool environments\n\nWhen running a tool with `uvx`, a virtual environment is stored in the uv cache directory and is treated as disposable, i.e., if you run `uv cache clean` the environment will be deleted. The environment is only cached to reduce the overhead of repeated invocations. If the environment is removed, a new one will be created automatically.\n\nWhen installing a tool with `uv tool install`, a virtual environment is created in the uv tools directory. The environment will not be removed unless the tool is uninstalled. If the environment is manually deleted, the tool will fail to run.\n\nImportant\n\nTool environments are _not_ intended to be mutated directly. It is strongly recommended never to mutate a tool environment manually, e.g., with a `pip` operation.\n\n## Tool versions\n\nUnless a specific version is requested, `uv tool install` will install the latest available of the requested tool. `uvx` will use the latest available version of the requested tool _on the first invocation_. After that, `uvx` will use the cached version of the tool unless a different version is requested, the cache is pruned, or the cache is refreshed.\n\nFor example, to run a specific version of Ruff:\n\n```\n$ uvx [email\xa0protected] --version\nruff 0.6.0\n\n```\n\nA subsequent invocation of `uvx` will use the latest, not the cached, version.\n\n```\n$ uvx ruff --version\nruff 0.6.2\n\n```\n\nBut, if a new version of Ruff was released, it would not be used unless the cache was refreshed.\n\nTo request the latest version of Ruff and refresh the cache, use the `@latest` suffix:\n\n```\n$ uvx ruff@latest --version\n0.6.2\n\n```\n\nOnce a tool is installed with `uv tool install`, `uvx` will use the installed version by default.\n\nFor example, after installing an older version of Ruff:\n\n```\n$ uv tool install ruff==0.5.0\n\n```\n\nThe version of `ruff` and `uvx ruff` is the same:\n\n```\n$ ruff --version\nruff 0.5.0\n$ uvx ruff --version\nruff 0.5.0\n\n```\n\nHowever, you can ignore the installed version by requesting the latest version explicitly, e.g.:\n\n```\n$ uvx ruff@latest --version\n0.6.2\n\n```\n\nOr, by using the `--isolated` flag, which will avoid refreshing the cache but ignore the installed version:\n\n```\n$ uvx --isolated ruff --version\n0.6.2\n\n```\n\n`uv tool install` will also respect the `{package}@{version}` and `{package}@latest` specifiers, as in:\n\n```\n$ uv tool install ruff@latest\n$ uv tool install [email\xa0protected]\n\n```\n\n## Upgrading tools\n\nTool environments may be upgraded via `uv tool upgrade`, or re-created entirely via subsequent `uv tool install` operations.\n\nTo upgrade all packages in a tool environment\n\n```\n$ uv tool upgrade black\n\n```\n\nTo upgrade a single package in a tool environment:\n\n```\n$ uv tool upgrade black --upgrade-package click\n\n```\n\nTool upgrades will respect the version constraints provided when installing the tool. For example, `uv tool install black >=23,<24` followed by `uv tool upgrade black` will upgrade Black to the latest version in the range `>=23,<24`.\n\nTo instead replace the version constraints, reinstall the tool with `uv tool install`:\n\n```\n$ uv tool install black>=24\n\n```\n\nSimilarly, tool upgrades will retain the settings provided when installing the tool. For example, `uv tool install black --prerelease allow` followed by `uv tool upgrade black` will retain the `--prerelease allow` setting.\n\nNote\n\nTool upgrades will reinstall the tool executables, even if they have not changed.\n\nTo reinstall packages during upgrade, use the `--reinstall` and `--reinstall-package` options.\n\nTo reinstall all packages in a tool environment\n\n```\n$ uv tool upgrade black --reinstall\n\n```\n\nTo reinstall a single package in a tool environment:\n\n```\n$ uv tool upgrade black --reinstall-package click\n\n```\n\n## Including additional dependencies\n\nAdditional packages can be included during tool execution:\n\n```\n$ uvx --with <extra-package> <tool>\n\n```\n\nAnd, during tool installation:\n\n```\n$ uv tool install --with <extra-package> <tool-package>\n\n```\n\nThe `--with` option can be provided multiple times to include additional packages.\n\nThe `--with` option supports package specifications, so a specific version can be requested:\n\n```\n$ uvx --with <extra-package>==<version> <tool-package>\n\n```\n\nThe `-w` shorthand can be used in place of the `--with` option:\n\n```\n$ uvx -w <extra-package> <tool-package>\n\n```\n\nIf the requested version conflicts with the requirements of the tool package, package resolution will fail and the command will error.\n\n## Installing executables from additional packages\n\nWhen installing a tool, you may want to include executables from additional packages in the same tool environment. This is useful when you have related tools that work together or when you want to install multiple executables that share dependencies.\n\nThe `--with-executables-from` option allows you to specify additional packages whose executables should be installed alongside the main tool:\n\n```\n$ uv tool install --with-executables-from <package1>,<package2> <tool-package>\n\n```\n\nFor example, to install Ansible along with executables from `ansible-core` and `ansible-lint`:\n\n```\n$ uv tool install --with-executables-from ansible-core,ansible-lint ansible\n\n```\n\nThis will install all executables from the `ansible`, `ansible-core`, and `ansible-lint` packages into the same tool environment, making them all available on the `PATH`.\n\nThe `--with-executables-from` option can be combined with other installation options:\n\n```\n$ uv tool install --with-executables-from ansible-core --with mkdocs-material ansible\n\n```\n\nNote that `--with-executables-from` differs from `--with` in that:\n- `--with` includes additional packages as dependencies but does not install their executables\n- `--with-executables-from` includes both the packages as dependencies and installs their   executables\n\n## Python versions\n\nEach tool environment is linked to a specific Python version. This uses the same Python version discovery logic as other virtual environments created by uv, but will ignore non-global Python version requests like `.python-version` files and the `requires-python` value from a `pyproject.toml`.\n\nThe `--python` option can be used to request a specific version. See the Python version documentation for more details.\n\nIf the Python version used by a tool is _uninstalled_, the tool environment will be broken and the tool may be unusable.\n\n## Tool executables\n\nTool executables include all console entry points, script entry points, and binary scripts provided by a Python package. Tool executables are symlinked into the executable directory on Unix and copied on Windows.\n\nNote\n\nExecutables provided by dependencies of tool packages are not installed.\n\nThe executable directory must be in the `PATH`variable for tool executables to be available from the shell. If it is not in the `PATH`, a warning will be displayed. The `uv tool update-shell` command can be used to add the executable directory to the `PATH` in common shell configuration files.\n\n### Overwriting executables\n\nInstallation of tools will not overwrite executables in the executable directory that were not previously installed by uv. For example, if `pipx` has been used to install a tool, `uv tool install` will fail. The `--force` flag can be used to override this behavior.\n\n## Relationship to `uv run`\n\nThe invocation `uv tool run <name>` (or `uvx <name>`) is nearly equivalent to:\n\n```\n$ uv run --no-project --with <name> -- <name>\n\n```\n\nHowever, there are a couple notable differences when using uv's tool interface:\n- The `--with` option is not needed — the required package is inferred from the command name.\n- The temporary environment is cached in a dedicated location.\n- The `--no-project` flag is not needed — tools are always run isolated from the project.\n- If a tool is already installed, `uv tool run` will use the installed version but `uv run` will   not.\n\nIf the tool should not be isolated from the project, e.g., when running `pytest` or `mypy`, then `uv run` should be used instead of `uv tool run`.                                                  November 24, 2025                                                                                                                                    Back to top                                                                                 Made with           Material for MkDocs"}]