uvx works but uv tool list is empty: check temporary execution versus installation

By ON Lab · Sources checked November 8, 2026

A successful uvx invocation does not by itself register a persistent tool in uv tool list or create a command in the tool executable directory. First check whether the tool is actually installed. If you need a lasting shell command, use the publisher’s verified distribution with uv tool install, then inspect the executable directory and your shell’s lookup separately.

The successful run and missing command are different observations

A macOS reader migrating from pipx could run a country-code program through uvx but could not find it in the installed-tool list or start it directly from the shell. Their tool executable directory was already in PATH. Adding that same directory again did not create the missing program.

This is a useful distinction when diagnosing “command not found.” One invocation may successfully prepare and run an application in a temporary environment, while the shell has no persistent command to find afterward. The word “Installed” during preparation describes packages in that environment; it does not establish that a shell entry point was registered.

What you observe	Next check
uvx works; tool list is empty	Decide whether temporary execution already meets your need
You need another program to invoke the command directly	Consider a verified persistent tool installation
Tool list includes it; the executable exists; shell lookup fails	Compare the actual executable directory with this shell’s PATH
A direct path fails too	Read that error before assuming shell lookup is the problem

Inspect registration before editing your shell

uv --version
uv tool list
uv tool dir --bin

These commands provide a version, installed-tool inventory and executable location. Keep their complete outputs together. Do not assume that a directory printed by uv tool dir --bin contains the command you need: a location and an existing file are separate facts.

If your tool is not listed, temporary execution may have worked exactly as intended. Continue using the verified uvx command if that is sufficient. Persistent installation is an operational choice, not a required repair for every successful one-off invocation.

What our isolated local test actually showed

We reused an inspected local wheel named desk-demo-dist, containing a single console command named desk-demo. The function only printed a fixed marker. We ran uv 0.13.7 on macOS using an existing interpreter. The test had its own cache, tool and executable directories inside a temporary working area; it did not change our normal shell configuration.

Before execution, uv tool list reported no installed tools and the test executable directory was empty. We then ran the local wheel with the correct executable name:

# Placeholder path: use an inspected local wheel, not a guessed public package
uv tool run --offline --no-python-downloads \
  --from /path/to/desk_demo_dist-1.0-py3-none-any.whl \
  desk-demo

The command exited with code 0 and printed our fixed success marker. Running uv tool list again still reported no installed tools. The test executable directory remained empty. A package preparation message appeared, but there was no new persistent shell command.

Next we deliberately installed that same local distribution into the isolated test tool location:

uv tool install --offline --no-python-downloads \
  /path/to/desk_demo_dist-1.0-py3-none-any.whl
uv tool list
uv tool dir --bin

Installation exited with code 0. The list now showed desk-demo-dist v1.0 with executable desk-demo, and the test bin directory contained that command. Running its full path printed the same marker and exited successfully. The application code was unchanged; persistent registration was the changed condition.

The installer also warned that our deliberately separate test bin directory was not on PATH. We left PATH alone and used the full path to check execution. This demonstrates why registration and shell lookup should be tested separately: the file can exist and work even while bare-name lookup would need a directory change.

Choose installation only when it solves the actual requirement

For a real application, obtain its current distribution name and installation instructions from its publisher. Installing a tool executes software and may download dependencies. Our local wheel example was deliberately small and offline; that result is not a review of another package’s contents.

After installation, verify three things in order: the intended distribution appears in the list, its documented command exists at the reported executable location, and the command can be invoked in the environment that needs it. A successful interactive terminal test does not establish that an editor, background job or other process has the same PATH.

On a Unix-like shell, command -v can show what a bare command resolves to. Use the actual command name, which may differ from the distribution name. For the separate naming problem, see pairing a uv distribution with its executable. That guide starts before the tool launches; this one starts after a temporary invocation has already worked.

Keep a narrow record when a persistent command still fails

Record the installed distribution and version, command name, executable directory, lookup result, and full-path result. If the full path succeeds but lookup selects nothing or another command, investigate the current caller’s search path. If the full path fails, preserve the interpreter or application error; changing PATH alone cannot explain that failure.

Avoid forcing an overwrite, deleting environments or repeatedly adding shell startup lines before those checks. Those changes can replace useful evidence or affect another installation. In our test, no overwrite or startup-file edit was necessary to establish what had and had not been installed.

Method: a historical reader report identifies the confusion; current official tool documentation supplies the execution/installation distinction; a local controlled wheel test supplies the observed inventory, bin-directory and exit-code results. We did not run the reader’s program or test every shell and operating system. A reusable cache is not a promise that a temporary environment will remain permanently installed.