`uv (sync|run) --only-group` doesn't include project

[cjw296]

I'm attempting to build the docs for a new project on Read the Docs.

I want to keep dependencies for this in a doc group:

[project]
...
requires-python = ">=3.12"
dependencies = []

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[dependency-groups]
docs = [
    "furo>=2024.8.6",
    "sphinx>=8.1.3",
]

The will be more groups later (dev, maybe build, etc).

When I attempt to sync and run with only that group, my project is uninstalled:

$ uv sync --only-group docs
Resolved 27 packages in 1ms
Uninstalled 1 package in 0.69ms
 - paradigms==0.0.0.dev1 (from file:///Users/chris/vcs/git/paradigms)
$ uv run --only-group docs sphinx-build -T -b html docs docs/_build/html/
Running Sphinx v8.1.3
...
importlib.metadata.PackageNotFoundError: No package metadata was found for paradigms

How should I be getting the project to be included here?

What's weird is that any other combination of uv sync and uv run where either of them does not have --only-group docs works:

$ uv sync
Resolved 27 packages in 1ms
Installed 1 package in 3ms
 + paradigms==0.0.0.dev1 (from file:///Users/chris/vcs/git/paradigms)
$ uv run --only-group docs sphinx-build -T -b html docs docs/_build/html/
Running Sphinx v8.1.3
...build succeeded.
The HTML pages are in docs/_build/html.

$ uv sync --only-group docs
Resolved 27 packages in 1ms
Uninstalled 1 package in 0.69ms
 - paradigms==0.0.0.dev1 (from file:///Users/chris/vcs/git/paradigms)
(docs) tweedledee:paradigms chris:
$ uv run sphinx-build -T -b html docs docs/_build/html/
Installed 1 package in 3ms
...
The HTML pages are in docs/_build/html.

This second permutation definitely feels like a bug...

[Ravencentric]

Use --group instead of --only-group.

[cjw296]

Use --group instead of --only-group.

If I have multiple default groups (since I want the developer experience to be "everything by default"), then how do I get the dependencies for only one of those groups?

Separately, what's the intended use case for --only-group if it doesn't include the project?

[Ravencentric]

You can use uv (sync|run) --group docs --no-group dev to install the project + docs while excluding dev group.

Separately, what's the intended use case for --only-group if it doesn't include the project?

Sometimes you don't need the project, e.g., a linter/formatter doesn't need the project installed so you can just use uv sync --only-group lint.

[charliermarsh]

It's intentional that --only-group does not include the project. If you want to run the project, with one group enabled, you'd use --group.

If I have multiple default groups (since I want the developer experience to be "everything by default"), then how do I get the dependencies for only one of those groups?

You would need to pass --no-default-groups (#10618).

What's weird is that any other combination of uv sync and uv run where either of them does not have --only-group docs works

The second uv run is re-installing your project. uv run will sync the project prior to running. It doesn't "remember" the state of the previous uv sync. You can try using --exact with uv run if you want a clearer model. By default, uv run will avoid removing dependencies unless necessary.

[cjw296]

It's intentional that --only-group does not include the project. If you want to run the project, with one group enabled, you'd use --group.

Okay, but --group gives a union of the default groups and the requested docs, right?

You would need to pass --no-default-groups

Okay, so get install the project and a single group, I need to do --no-default-groups --group docs?

[cjw296]

Hmm, when is --no-default-groups expected to make it into a release?

$ uv self update
info: Checking for updates...
success: Upgraded uv from v0.5.18 to v0.5.21! https://github.com/astral-sh/uv/releases/tag/0.5.21
$ uv sync --no-default-groups --group docs
error: unexpected argument '--no-default-groups' found

[charliermarsh]

Please follow the linked PR; it’s still open.