uvx (uv tool run): Run a Tool Without Installing
uvx runs a command-line tool in a temporary, cached environment without permanently installing it.
uvx (a shortcut for uv tool run) is ideal in CI: it fetches a tool, runs it, and leaves no global state. Pin the version for reproducible jobs.
What it does
uvx resolves and installs the requested tool into a cached ephemeral environment, then executes its entry point. When the command name differs from the package name, --from names the package. The environment is reused from cache on later runs.
Common usage
uvx ruff check .
uvx ruff@0.6.9 check .
uvx --from httpie http GET https://example.com
uvx --with rich pytest
uvx black --versionOptions
| Flag | What it does |
|---|---|
| --from <pkg> | Package to install when it differs from the command |
| --with <pkg> | Add extra packages to the ephemeral environment |
| <tool>@<version> | Pin an exact version of the tool to run |
| --python <version> | Run the tool on a specific Python |
| --isolated | Ignore any project and run fully isolated |
In CI
Pin the tool version (ruff@0.6.9) so a new release cannot change your job behavior overnight. Cache $UV_CACHE_DIR so the ephemeral environment is reused across runs. uvx needs no PATH setup, which makes it the cleanest way to run linters and formatters in pipelines.
Common errors in CI
"error: Failed to parse ... <name> could not be found" with a hint about --from means the command name does not match the package; add --from. "No solution found" on a pinned version means that version is yanked or incompatible with the chosen Python. A typo command yields "executable <x> not found in package".