How to Run Python CLI Tools with uvx: Complete Command Guide

Mar 5, 2026

Tired of installing one-off Python CLI tools that clutter your system? I was too - until I discovered uvx. It lets me run Python CLI tools without polluting my environment, and it’s 10-100x faster than pip.

Let me show you every uvx command you’ll actually use.

What is uvx?

uvx is simply an alias for uv tool run. It’s Astral’s answer to running Python tools ephemerally - meaning the tool runs in an isolated environment, does its job, and leaves no trace on your system.

Think of it as “npx for Python” - you run a tool once without installation, and it just works.

Why this matters:

No environment pollution: Your system stays clean
Version isolation: Each tool runs with its exact dependencies
Blazing fast: uv is 10-100x faster than pip for resolution and installation

Basic uvx Commands

Running a tool is straightforward:

# Basic syntax
uvx <tool-name>

# Real examples
uvx pycowsay 'Hello World'
uvx ruff check .
uvx black .
uvx mypy src/

The first run downloads and caches the tool. Subsequent runs are much faster.

When you run uvx, you’ll see output like:

Resolved 1 package in 167ms
Installed 1 package in 12ms

This shows uvx resolving the package, installing it to its cache, and running it - all in milliseconds.

Passing Arguments to Tools

Everything after the tool name gets passed directly to the tool:

# Pass arguments to the tool
uvx pycowsay 'Custom message here'
uvx ruff check . --fix
uvx black src/ --check
uvx http https://example.com

This is intuitive - uvx passes your arguments through to the underlying tool without interference.

Version Pinning and Constraints

Need a specific version? Use the @ syntax:

# Run exact version
uvx [email protected] check

# Run latest version
uvx ruff@latest check

For more complex version requirements, use the --from flag with PEP 440 specifiers:

# Version range
uvx --from 'ruff>0.2.0,<0.3.0' ruff check

# Minimum version
uvx --from 'ruff>=0.3.0' ruff check

The --from flag changes the package source entirely, which is useful when you need fine-grained control over versions.

Running Tools from Different Packages

Sometimes the CLI command name differs from the package name. Use --from to specify the package explicitly:

# httpie CLI is in the 'httpie' package
uvx --from httpie http

# Sometimes needed for conflicting names
uvx --from package-name tool-name

This solves the “tool not found” problem when a package provides multiple CLI commands.

Using Extras

Many packages have optional extras that include additional tools:

# Install with extras
uvx --from 'mypy[faster-cache,reports]' mypy --xml-report report

# Common extras patterns
uvx --from 'package[extra1,extra2]' tool-name

Extras are useful for enabling specific features without installing everything.

Running from Git Sources

Want to test an unreleased version or a PR? Run directly from git:

# From git repository
uvx --from git+https://github.com/httpie/cli httpie

# From specific branch or tag
uvx --from git+https://github.com/user/repo@branch-name tool-name

# From pull request
uvx --from git+https://github.com/user/repo@pull/123/head tool-name

This is invaluable for testing bleeding-edge features or contributing to open source.

Adding Plugins with —with

Need a temporary plugin? Use --with:

# Add plugins temporarily
uvx --with mkdocs-material mkdocs --help

# Multiple plugins
uvx --with plugin1 --with plugin2 tool-name

Common use cases:

mkdocs themes
pytest plugins
black configurations

The --with flag adds packages to the tool’s environment without modifying your system.

Common Practical Examples

Here are commands I use daily:

Code Quality Tools

# Linting with ruff
uvx ruff check .
uvx ruff@latest check . --fix

# Code formatting
uvx black .
uvx isort .

# Type checking
uvx mypy src/
uvx pyright src/

Development Tools

# HTTP clients
uvx http GET https://api.example.com
uvx httpie https://example.com

# Package tools
uvx pip-audit  # Check for vulnerabilities
uvx pip-tools compile  # Compile requirements

# Testing
uvx pytest tests/
uvx coverage run -m pytest

Fun/Practical Tools

# Just for fun
uvx pycowsay 'Hello from uvx'
uvx cowsay 'Welcome to uvx'

# Generate passwords
uvx --with passlib python -c "from passlib.hash import bcrypt; print(bcrypt.hash('password'))"

uvx vs uv tool run

They’re exactly the same. uvx is a convenient alias for uv tool run. Use whichever reads better in your workflow:

# These are identical
uvx ruff check .
uv tool run ruff check

Performance Tips

First run: Downloads and caches the tool (~1-2 seconds)
Subsequent runs: Nearly instant (milliseconds)
CI/CD: Pin versions for reproducibility
Debugging: Use --no-cache when troubleshooting

# Disable cache if needed
uvx --no-cache ruff check .

Troubleshooting Common Issues

Tool not found

# Try specifying package explicitly
uvx --from package-name tool-name

Version conflicts

# Use version constraints
uvx --from 'package>1.0,<2.0' tool

Permission errors: uvx handles this automatically. No sudo needed.

Quick Reference

Use Case	Command
Basic run	`uvx tool-name`
With args	`uvx tool arg1 arg2`
Specific version	`uvx [email protected]`
Version range	`uvx --from 'tool>1.0' tool`
From package	`uvx --from pkg tool`
With plugins	`uvx --with plugin tool`
From git	`uvx --from git+https://... tool`

Conclusion

uvx is now my go-to for running Python CLI tools. No more pip install for one-off tools. No more environment pollution. Just run and done.

The key commands to remember:

uvx tool - basic usage
uvx tool@version - version pinning
uvx --from - flexible sourcing
uvx --with - adding plugins

Try it now:

uvx pycowsay "uvx rocks!"

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!