uv --with installed the package but its command is missing: inspect dependency executables

By ON Lab · Sources checked November 8, 2026

An additional package can be installed in a uv tool environment without its executable being placed in the tool bin directory. If the main program can import the dependency but the dependency’s own command is missing, distinguish --with from --with-executables-from. Verify the actual package that provides the command before changing the installation.

Identify which command is missing

In a reader discussion about Ansible, installing the top-level distribution exposed one command while commands supplied by a related package were absent from the executable directory. This is different from a tool that was only run temporarily, and different from spelling the main command incorrectly.

Start with the exact installation command, uv version, installed-tool inventory and the command you expected. A list of installed packages is not the same as a list of exported executables. Keep the main distribution, additional distribution and missing command on separate lines so that the next change targets the right relationship.

Need	Relevant distinction
The main tool needs an extra import or plugin	The extra package must be present in its environment
You also need to call the extra package’s own command	That command must be exposed in the executable directory
The main distribution provides no command at all	Confirm which distribution actually supplies the entry point
A file with the target name already exists	Identify its owner before considering an overwrite

Compare the two installation requests

Current uv documentation describes an option for including an additional package and another for including that package’s executables as well. Using placeholders, the requests are:

uv tool install --with EXTRA_PACKAGE MAIN_PACKAGE
uv tool install --with-executables-from EXTRA_PACKAGE MAIN_PACKAGE

Replace the placeholders only with verified distribution names. This guide did not install Ansible, LocalStack or their dependencies. A publisher’s package arrangement can change, so an old issue is evidence of a reader problem rather than a current installation recipe for that application.

A controlled test: import works in both cases

We prepared two small local wheels for uv 0.13.7 on macOS. The main distribution, desk-parent, supplied a command named desk-parent. That command imported desk_helper and printed HELPER_IMPORT_OK. The extra distribution, desk-helper, supplied that module and its own desk-helper console command.

Both wheels contained inspected Python code and ordinary wheel metadata, with no third-party requirements. They were tested using an existing interpreter and separate cache, tool and bin directories for each case. The main wheel and the helper wheel stayed the same; only the executable-inclusion option changed.

# Illustrative paths to the two locally prepared wheels
uv tool install --offline --no-python-downloads --no-index \
  --find-links /path/to/local-wheels \
  --with desk-helper \
  /path/to/local-wheels/desk_parent-1.0-py3-none-any.whl

The first installation succeeded and reported two installed packages. Its bin directory contained only desk-parent. Running that command by its full path succeeded and printed HELPER_IMPORT_OK. The helper module was therefore available to the main program, even though the helper’s separate shell command was not exposed.

In a fresh test tool location, we ran the second case:

uv tool install --offline --no-python-downloads --no-index \
  --find-links /path/to/local-wheels \
  --with-executables-from desk-helper \
  /path/to/local-wheels/desk_parent-1.0-py3-none-any.whl

This installation also succeeded with the same two packages. Its bin directory contained desk-parent and desk-helper. The parent command still printed the same import marker. We used full paths for these checks and did not modify our shell startup files.

Test observation	With additional package	With its executables too
Installation exit code	0	0
Parent can import helper	Yes	Yes
Parent command in bin	Yes	Yes
Helper command in bin	No	Yes

Verify exposure separately from shell lookup

uv tool list
uv tool dir --bin

Inspect the directory returned by the second command. If the expected executable is present, check whether the calling terminal or application can find it. If it is absent, adding that directory to PATH again will not create the file. Our local test deliberately used separate bin locations, so the installer’s PATH warning was expected and was not treated as an installation failure.

When you need a plugin but do not need its standalone command, the first form may already meet the requirement. Exporting every related command creates more names to manage and potentially more collisions. Choose the smallest installation that supports the actual workflow.

Keep old bug reports separate from present behavior

A separate historical LocalStack report involved a distribution without its own entry points and a confusing existing-executable error. We did not reproduce that application or infer that its old failure remains in today’s uv. The controlled test here establishes only the additional-package versus additional-executable boundary.

If an existing executable conflict appears, record its path and origin before changing anything. A forced overwrite can replace a command supplied by another installation. If the provider relationship is unclear, consult the current package instructions with your exact uv version rather than copying a workaround from a different environment.

For related but distinct problems, use the distribution-versus-command naming check or the temporary execution versus persistent installation check. Neither is a reason to change project dependencies or delete a lockfile when the missing object is a tool executable.

Method: historical reader reports establish the problem; current official tool documentation supplies the supported distinction; two inspected local wheels supply the observed import and bin results. The test did not validate every operating system, external package or executable-conflict scenario.