What is uvx? A Practical Guide to uvx vs uv tool

Mar 5, 2026

Problem

I’ve been using uv for Python project management and I love it. I use uv tool install for tools I want to keep around. But I keep seeing uvx mentioned everywhere.

Here’s what confused me: Why would I want a tool that removes itself after use? Isn’t that wasteful? Shouldn’t I just install everything permanently?

Let me share what finally clicked for me.

The Short Answer

TL;DR: Use uvx for one-off commands, use uv tool install for tools you run frequently.

# Ephemeral - tool is removed after use
uvx ruff check .

# Permanent - tool stays installed
uv tool install ruff
ruff check .

Key realization: uvx is just an alias for uv tool run. They’re literally the same thing.

What is uvx?

uvx executes a Python tool in an isolated, temporary environment.

Here’s what happens when I run it:

$ uvx pycowsay 'hello world!'
Resolved 1 package in 0.23ms
Installed 1 package in 12ms
  _____________
| hello world! |
  =============
              \
               \
                 ^__^
                 (oo)\_______
                 (__)\       )\/\
                     ||----w |
                     ||     ||

Behind the scenes, uv:

Resolves the required package
Installs it temporarily
Runs the tool
Cleans up (package removed after use)

The next time I run the same command, uv uses its cache, so it’s fast:

$ uvx pycowsay 'hello again!'
Resolved 1 package in 0.15ms
Installed 1 package in 0.88ms  # Much faster - from cache
  _____________
| hello again! |
  =============
              \
               \
                 ^__^
                 (oo)\_______
                 (__)\       )\/\
                     ||----w |
                     ||     ||

I can also pin specific versions:

# Use a specific version
uvx [email protected] check .

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

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

What is uv tool install?

uv tool install permanently installs a Python tool to my system.

# Install permanently
$ uv tool install ruff
Resolved 1 package in 23ms
Installed 1 package in 12ms
Installed ruff v0.3.0

# Now available globally
$ ruff --version
ruff 0.3.0

$ ruff check .
Found 0 errors.

The tool stays in my environment until I explicitly uninstall it:

$ uv tool uninstall ruff
Uninstalled ruff

When to Use uvx (Ephemeral)

Occasional Tools

Tools I run once in a while or across different projects:

# Clean .pyc files - I do this maybe once a week
uvx pyclean .

# Make a quick API call - once a month maybe
uvx httpie GET https://api.example.com/status

# Just for fun
uvx cowsay 'testing'

The Reddit comment that made it click: “I don’t want to install it to every venv.” That’s the key - these tools don’t belong in my project dependencies, and I don’t need them cluttering my system.

Trying New Tools

Before committing to installation:

# Test drive a tool
uvx httpie

# Try different versions
uvx ruff@latest check .
uvx [email protected] check .

CI/CD Pipelines

Ephemeral is perfect for CI where I don’t want tool pollution:

- name: Lint with ruff
  run: uvx ruff check .

No leftover packages, no cleanup needed, fresh version each time.

Project-Specific Versions

When a project needs a specific version:

# Project requires ruff 0.3.0
uvx [email protected] check .

# Another project uses latest
uvx ruff@latest check .

When to Use uv tool install (Permanent)

Daily Driver Tools

Tools I use multiple times per day:

# I run this dozens of times daily
uv tool install ruff

# My go-to formatter
uv tool install black

If I’m running a tool 10+ times per day, the ephemeral install overhead adds up. Permanent is faster.

Editor Integration

Tools that need to be in PATH for my editor:

# VS Code needs to find these
uv tool install pyright
uv tool install ruff

My .vscode/settings.json:

{
  "python.linting.enabled": true,
  "python.linting.ruffEnabled": true,
  "python.formatting.provider": "none",
  "[python]": {
    "editor.formatOnSave": true,
    "editor.defaultFormatter": "charliermarsh.ruff"
  }
}

The editor can’t call uvx - it needs the tool in PATH.

Side-by-Side Comparison

Aspect	uvx (ephemeral)	uv tool install (permanent)
Installation	Temporary, cached	Permanent
Version control	Easy to pin/change	Requires reinstall
Disk space	No leftover packages	Stays in tools directory
Speed (first run)	Resolves + installs	Resolves + installs
Speed (subsequent)	Uses cache	Instant (already there)
Cleanup	Automatic	Manual uninstall
Best for	Occasional use	Daily use
Editor integration	No	Yes

Decision Framework

I ask myself these questions:

1. How often will I run this?

Once a week or less → uvx
Daily → uv tool install

2. Do I need a specific version pinned to a project?

Yes, project-specific → uvx [email protected]
Latest is fine → Either

3. Does my editor need to find it?

Yes → uv tool install
No → uvx

4. Is this for CI/CD?

Yes → uvx (cleaner pipelines)

Summary

In this post, I explained the difference between uvx and uv tool install. The key point is: there’s no wrong choice - just different tools for different jobs.

I can start with uvx to try something out, and graduate to uv tool install when a tool becomes essential to my daily workflow.

The beauty is flexibility - I’m not locked into either approach.

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:

👨‍💻 uv Documentation
👨‍💻 uv tool run reference
👨‍💻 Astral - uv creators

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