Skip to content

Using uv run as a task runner #5903

Open

Description

@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:

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.

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.

Activity

  1. chrisrodrigue commented on Aug 8, 2024

    @chrisrodrigue

    Relevant comment from another issue: #5632 (comment)

  2. chrisrodrigue commented on Aug 8, 2024

    @chrisrodrigue
  3. added
    enhancementNew feature or improvement to existing functionality
    previewExperimental behavior
    on Aug 9, 2024
  4. charliermarsh commented on Aug 9, 2024

    @charliermarsh
    Member

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

  5. nikhilweee commented on Aug 9, 2024

    @nikhilweee
  6. charliermarsh commented on Aug 9, 2024

    @charliermarsh
    Member

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

  7. chrisrodrigue commented on Aug 9, 2024

    @chrisrodrigue

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

  8. nikhilweee commented on Aug 10, 2024

    @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.

  9. cdwilson commented on Aug 23, 2024

    @cdwilson
  10. chrisrodrigue commented on Aug 23, 2024

    @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]).

  11. pietroppeter commented on Aug 28, 2024

    @pietroppeter

    since it has not been mentioned yet, adding as a possible inspiration for design of tasks also pixi: https://pixi.sh/latest/features/advanced_tasks/

  12. metaist commented on Aug 28, 2024

    @metaist

    I happen to be writing a cross-project task runner that supports a bunch of formats (e.g. rye, pdm, package.json, Cargo.toml; even uv's workspace config).

    For what it's worth, almost all python runners use tool.<name>.scripts for task config (presumably inspired by npm's package.json format), so it's somewhat of an easier upgrade path for people coming from other tools.

    https://github.com/metaist/ds

  13. inoa-jboliveira commented on Sep 8, 2024

    @inoa-jboliveira

    Also related to this thread, I wish uvx was uv run instead of uv tool run when inside a project.

    uv tool run seems like something you would do to play with a tool, like ruff. But then you will eventually uv add ruff --dev and forever keep writing uv run ruff check instead of uvx ruff check which won't respect the locked version and will be in different virtualenv. It also means the tool could be running on a different Python (does not apply to ruff, but any other python lib) and all sorts of weird stuff can happen.

    I know uv run stuff is still short, but it could be 4 keystrokes shorter.

    Regarding uv run being a task runner it means people will type it waaaaay more often than uv tool run.
    I would appreciate a dedicated command like uvr

  14. 256 remaining items

  15. roman-k-kaimakov commented on Apr 21, 2026

    @roman-k-kaimakov
  16. EED85 commented on Jun 11, 2026

    @EED85

    Hi all,

    Currently, upgrading multiple specific packages requires repeating the flag:

    uv sync --upgrade-package marimo --upgrade-package polars --upgrade-package hvplot

    It would be great to support defining aliase so it could be shortened to

    uv upgrade-packages marimo polars hvplot (for example)

  17. christiansegercrantz commented on Jun 11, 2026

    @christiansegercrantz

    Hi all,

    Currently, upgrading multiple specific packages requires repeating the flag:

    uv sync --upgrade-package marimo --upgrade-package polars --upgrade-package hvplot

    It would be great to support defining aliase so it could be shortened to

    uv upgrade-packages marimo polars hvplot (for example)

    This feels like a separate topic, not something a uv run would be used for. This should be a built-in feature if it would be implemented

  18. tback commented on Jun 11, 2026

    @tback
  19. krzkaczor commented on Aug 31, 2026

    @krzkaczor

    For those who cares (especially while working with workspaces), uv-tasks does most of the needed things:

    • define tasks in pyproject.toml:
    [tool.ut.tasks]
    test = "pytest -s"
    typecheck = "ty check ."
    check = ["ruff check .", "ty check ."]   # a sequence: stops at the first failure
    
    • runs in workspaces, in parallel, parents first:
    # root pyproject.toml
    [tool.ut.tasks]
    test = "ut run -w test"                  # run every member's "test"
    check = ["ut run -w lint", "ut run -w test"]
    

    It works in a way that does single uv sync --all-packages before executing scripts so there might be some collisions between scripts. Watch out for this if you have name collisions across your workspace.

    I am surprised that uv doesn't come with something built-in and I would be more than happy to champion this. At this stage it's quite simple but it works well for my needs. Ohh and I've vibeslopped it in rust so it's blazingly fast ;)

  20. ksamuel commented on Sep 1, 2026

    @ksamuel

    Please don't spam this thread with your grab for attention.

    The whole point of this is to have a well designed, high quality and strongly integrated solution. If you are going to offer a low-effort, vibecoded, half-baked workaround that doesn't even bring anything on top of just and shows you clearly haven't read any part of the previous discussion, you don't bring anything to the table.

  21. Enzo-Agosta commented on Sep 25, 2026

    @Enzo-Agosta

    I'd like to try and recenter the discussion if we can. Everyone mostly agreed on @lucabello's alias approach a while ago, and for good reason I think. Below is what I think the design should look like, to try and move the discussion further.

    AI Note: GPT and Opus helped me in refining my arguments and they wrote the draft of this comment. But I stand behind every word as if they were mine, and I rewrote most of the prose myself.

    The one rule I think uv task should follow religiously is:

    uv task [OPTIONS] <name> [ARGS] behaves exactly like uv run [OPTIONS] <task argv> [ARGS], run from the directory of the project that defines the task.

    The design I personally envision looks something like

    [tool.uv.tasks]
    lint = ["ruff", "check"]
    format = ["ruff", "format", "--check"]
    typecheck = ["ty", "check"]
    test = ["--group", "test", "pytest", "-q"]
    docs = ["--group", "docs", "sphinx-build", "-M", "html", "docs", "docs/_build"]
    
    [tool.uv.task-sequences]
    ci = ["lint", "format", "typecheck", "test"]

    In this situation:

    • uv task lint runs uv run ruff check
    • uv task docs runs uv run --group docs sphinx-build ...
    • uv task --locked ci runs the four tasks in order, each one with --locked

    Since tasks is really just arguments for uv run, we inherit all of the limitations but also all of the benefits of uv run. We don't need to design anything new for dependency groups, env files, --frozen or workspaces.
    Whatever uv run supports, uv tasks supports it, and conflicting options fail the same way they already do. Tasks are argument lists rather than strings so there is no command-line parsing to specify; that costs some punctuation, but tasks are written once and run many times.

    To go through the rest of the semantics:

    • uv task with no name lists the tasks and sequences. It never runs anything, so it's always safe to type in an unfamiliar repo. (This is also why I'd skip a default task, see here)
    • uv task is its own command, so task names never shadow executables in uv run.
    • Arguments after the task name are appended: uv task test -k login. Sequences reject extra arguments rather than guessing which step should get them.
    • A sequence runs its steps in order, and each step behaves exactly as its own uv run would. I would argue for stopping the sequence on the first failure and returning that exit code.
    • Sequences can only reference tasks in the same project, not other sequences, and all references are validated before anything runs.
    • Sequences live in a separate table because a sequence and a command are both lists of strings. (Note: an inline table like ci = { sequence = [...] } is something I'm fully fine with and would allow for adding help docs or more options without much trouble in the future.)
    • Tasks are looked up in the current project or the member selected with --package, with no fallback to the workspace root.

    If we want this to actually be something maintainable and implementable I would explicitly keep all the below out of scope:

    • No Shell: I will die on this hill. No expansion, no globbing, $VARS, &&, or pipes. Once any of that is supported, uv has to define a shell dialect and make it behave the same on Windows. deno task already did it, and they had to build their own shell to make it truly portable. I don't think that's a burden uv should take on, at least not now.
    • No task-specific environments, dependency graph between tasks, caching, hooks, parallel steps, or running a task across every workspace member.
    • No attempt to replace Poe, taskipy, just, or nox. Anything that needs more than a list of commands still belongs there (or in a Python script).

    On @zanieb's question about what uv adds over re-implementing Poe:

    • It works on a fresh clone with only uv installed. No task runner has to be synced into the environment first.
    • It's portable by construction, since nothing goes through a shell.
    • Projects that only need "the same few commands, tracked in git instead of in the README" don't need an extra dev dependency. Projects that need more still reach for Poe and friends, so this doesn't compete with them.
    • It fits next to dedicated commands like uv format rather than against them.

    On the standards discussions: a scope this small should be small and easy enough to map onto whatever gets standardized later, since it can only grow, not conflict.

    The one thing I'd like to hear from maintainers would be regarding the strict "a task is exactly a uv run invocation" rule I propose. Is this a constraint you would be willing to accept, and are there uv run options you wouldn't want reachable from a task definition?

  22. mfisher87 commented on Sep 29, 2026

    @mfisher87

    No Shell: I will die on this hill. No expansion, no globbing, $VARS, &&, or pipes. Once any of that is supported, uv has to define a shell dialect and make it behave the same on Windows. deno task already did it, and they had to build their own shell to make it truly portable. I don't think that's a burden uv should take on, at least not now.

    What does this look like to you? Validating the command and throwing an error if e.g. && is present? Or allow the user to use whatever they want and if they run it on an incompatible shell that's their problem?

  23. AI0867 commented on Sep 30, 2026

    @AI0867

    What does this look like to you? Validating the command and throwing an error if e.g. && is present? Or allow the user to use whatever they want and if they run it on an incompatible shell that's their problem?

    I'm guessing, that invoking uv task foo bar baz, when tool.uv.tasks.foo = ["something", "&&", "else"],
    will run something equivalent to uv run something "&&" else bar baz, or somewhat more accurately,
    execve(UV, ["uv", "run", "something", "&&", "else", "bar", "baz"]), with no shell being involved. If those args mean something to the "something" that is getting run, great. If not, that's a problem for who defined the task or passed the args.

    If you want shell support, you can define a task tool.uv.tasks.bash = ["bash"] or something like that, but then it's on you to make sure bash is installed.

  24. Enzo-Agosta commented on Sep 30, 2026

    @Enzo-Agosta

    If those args mean something to the "something" that is getting run, great. If not, that's a problem for who defined the task or passed the args.

    That sums it up nicely, @AI0867. TOML gives us an array of strings, which become arguments to uv run. Nothing interprets them as shell syntax. &&, $VARS, and glob patterns are passed literally to the executable. That’s what I mean by no shell.

    There would be no validation for shell syntax either. As you said, whether those arguments mean anything is up to the program receiving them.

    Someone could explicitly invoke a shell, just as they can with uv run today. But I’d be reluctant to document or encourage that as an escape hatch. My concern is that users would reasonably see a task defined under [tool.uv.tasks] as something uv supports, then report problems to uv when the shell is missing, its syntax differs across platforms, or paths behave differently.

    Even if we document where uv’s responsibility ends, those reports still create work for maintainers. Part of the argument for this proposal is its limited scope and maintenance burden. Encouraging shell invocation weakens that argument, so I’d keep the feature and its recommended usage focused on passing literal arguments to executables.

  25. added 2 commits that reference this issue on Nov 9, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or improvement to existing functionalityneeds-designNeeds discussion, investigation, or design

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions