Should uvx use a project dependency if available?

[zanieb]

Right now, uvx will run in an isolated environment even if the target tool is installed in the current project. For example, uvx ruff will not use the version of Ruff declared in the project (e.g., with uv add ruff==0.3.0). If we're in a project, it might make sense to respect the version there instead of ignoring it?

This may be a reasonable way to support defining tools in projects until we design and implement "project-level tool definitions" per #3560.

Related:

• Should uvx warn if the command is present in the project environment? #6377
• Using uv run as a task runner #5903 (comment)
• RFC: Tool management #3560

[helderco]

My preference is to reserve uvx for stuff in .venv/bin (like npx) since uv tool install ruff can create symlinks for the tool's binaries in a place that can be added to the $PATH (like pipx) and run with simply ruff.

[zanieb]

My preference would be to use uv tool run, but place symlinks for the tools in a directory that can be added to the $PATH

Isn't this just uv tool install?

That way, I could install ruff globally with uv tool install ruff, run it with just ruff check, and use uvx for stuff in .venv/bin (like npx with node_modules/bin).

Except npx will also run arbitrary versions without installing them, right? I'm not sure I follow.

[helderco]

Sorry, I'm on my phone so I can't try things. Reworded my previous comment right after posting.

Didn't know npx could run commands without installing. I don't personally use it now but did a few years ago, when npx came out it was used just for easily running installed binaries in the project.

For global installations I rather use the $PATH. I do use uv run a lot and would prefer uvx be used to shorten that. As for running without installing, could uvx try these in turn?

• in .venv
• in tools dir
• isolated

[zanieb]

Yep that's the suggestion this issue tracks.

[inoa-jboliveira]

Currently uvx is really just a shorthand for uv tool run but it could be a more intelligent command using context.

Meaning it will either call uv run or uv tool run as necessary. And if you actually mean one or the other, you could force it by using the explicit form. If you bake "run" inside "tool run", you lose this ability.

I don't know if that is feasible as these commands have different options. My original suggestion was to have a 3rd command but I am seeing it as more confusing to the end user than a smarter uvx

[zanieb]

The idea here is that uv tool run would check the project for the dependency too. You'd use --no-project to ignore the project dependency declaration. I don't think uvx will ever have different semantics than uv tool run (it'd be too confusing).

[matterhorn103]

This actually seems to be two different questions, no?

1. Should uv tool run ruff use the version of ruff installed in the project, if there is one, rather than the global/tools version?
2. If uv tool run ruff uses a project version of ruff, should it be run in the project environment or in an isolated one?

Because so far as I can see (with my limited knowledge of the problem) it would be theoretically possible to do 1 but not 2, no? I.e. reuse the installed wheel but still run it in an isolated environment?

While I'm here, my feedback would be that this seems to me on the face of it not such a great idea. The whole "tool" interface is already a little challenging for newcomers conceptually (was for me, anyway). Assuming that both 1) and 2) are being proposed, this proposal would muddy the waters and make it even more confusing, as the behaviour of uv tool run would vary, and it might not always be clear what is being invoked. Learning and teaching becomes harder as it is no longer possible to break it down as "uv tool uses global/isolated packages and environments and uv run uses local/project packages and environments".

Sometimes it makes a big difference whether a tool-like package runs in an environment or not (e.g. pyinstaller), and then the clear delineation of the two behaviours is useful and crucial.

If anything I would say that uvx having different behaviour to uv tool run is less confusing than having uv tool run show context-dependent behaviour. But both are a little confusing.

If using the project dependency with uv tool run was implemented, I think it'd be much more user-friendly if it was off by default and turned on with e.g. --use-project rather than the other way round.

[inoa-jboliveira]

I've been using uv run lately to have tools available in the current env of a project without having it installed as a dependency. Tools such as ones that are useful once in a blue moon such as checking for licenses of libs:

uv run --with pip-licenses -- pip-licenses

This is what I would hope for uvx to be when running inside a project. Notice this must run in the project env to find the libraries.

Reading the docs: Relationship to uv run

For uv run to behave like uvx, it would require --no-project and replace (optional) --from with --with.

So why can't uvx just have a --project flag and a UVX_PROJECT=true env var which would behave like uv run?

This would be very easy to implement and save us a lot of keystrokes and mental gymnastics to remember the usage.