Using `uv run` as a task runner

[my1e5]

For those of us migrating over from Rye, one of its nice features is the built-in task runner using rye run and [tool.rye.scripts]. For example:

[tool.rye.scripts]
hello = "echo Hello from Rye!"

$ rye run hello
Hello from Rye!

It could have some more features - here is a selection of feature requests from the community:

• Allow shell expansion/interpolation in rye run command rye#695
• Allow to define local variable in rye scripts rye#652
• ✨ Allow passing cwd in tool.rye.scripts rye#930
• Support for pre-/post-hooks in Rye custom scripts rye#1243

A lot of these requested features are things that other 3rd party tools currently offer. I thought it might be useful to highlight a few other tools here, in particular because they also integrate with the pyproject.toml ecosystem and can be used with uv today.

• Poe the Poet

  https://github.com/nat-n/poethepoet

  uv add --dev poethepoet
  

  [tool.poe.tasks]
  hello = "echo Hello from poe!"
  

  $ uv run poe hello
  Poe => echo Hello from 'poe!'
  Hello from poe!
  

• taskipy

  https://github.com/taskipy/taskipy

  uv add --dev taskipy
  

  [tool.taskipy.tasks]
  hello = "echo Hello from taskipy!"
  

  $ uv run task hello
  Hello from taskipy!
  

Perhaps these can serve as some inspiration for a future uv run task runner and also in the meantime offer a solution for people coming over from Rye looking for a way to run tasks.

[chrisrodrigue]

Relevant comment from another issue: #5632 (comment)

[chrisrodrigue]

PDM supports this: https://pdm-project.org/latest/usage/scripts/

[charliermarsh]

Yeah we plan to support something like this! We haven't spent time on the design yet.

[nikhilweee]

The pyproject standard already supports [project.scripts], so uv may not need to use its own table.
https://packaging.python.org/en/latest/guides/writing-pyproject-toml/#creating-executable-scripts

[charliermarsh]

[project.scripts] is a little different -- that's used to expose specific Python functions as executable scripts, and we do support that already.

[chrisrodrigue]

Perhaps naming this section tool.uv.tasks or tool.uv.aliases could help disambiguate that.

[nikhilweee]

Or maybe [tool.uv.run] to be consistent with the command uv run. Or we could even think about [tool.uv.commands].
I'm not a big fan of [tool.uv.scripts] since it conflicts with [project.scripts] and I myself got confused before.

[cdwilson]

This is the main thing I missed coming from hatch: https://hatch.pypa.io/dev/config/environment/overview/#scripts

[chrisrodrigue]

+1 to @nikhilweee suggestions. I think “command” reflects the intent/concept.

Hatch has an “environment” concept and supports running commands namespaced to an environment like so

hatch run test:cov

where “test” is a user-defined environment (with a dependency group) and “cov” is a user-defined command for that environment.

[tool.hatch.envs.test]
dependencies = [
 "pytest",
 "pytest-cov",
 "pytest-mock",
 "freezegun",
]

[tool.hatch.envs.test.scripts]
cov = 'pytest --cov-report=term-missing --cov-config=pyproject.toml --cov=src'

[[tool.hatch.envs.test.matrix]]
python = ["3.8", "3.9", "3.10", "3.11", "3.12"]

I would be curious to hear the use cases of nesting dependency groups and commands into “environments” like this rather than defining them at the top-level (i.e. [tool.uv.commands]/[tool.uv.dev-dependencies]).