Zanie Blue
8f71d239f8
Revives https://github.com/astral-sh/uv/pull/9130 Previously, we allowed scoping conflicting extras or groups to specific packages, e.g. ,`{ package = "foo", extra = "bar" }` for a conflict in `foo[bar]`. Now, we allow dropping the `extra` or `group` bit and using `{ package = "foo" }` directly which declares a conflict with `foo`'s production dependencies. This means you can declare conflicts between workspace members, e.g.: ``` [tool.uv] conflicts = [[{ package = "foo" }, { package = "bar" }]] ``` would not allow `foo` and `bar` to be installed at the same time. Similarly, a conflict can be declared between a package and a group: ``` [tool.uv] conflicts = [[{ package = "foo" }, { group = "lint" }]] ``` which would mean, e.g., that `--only-group lint` would be required for the invocation. As with our existing support for conflicting extras, there are edge-cases here where the resolver will _not_ fail even if there are conflicts that render a particular install target unusable. There's test coverage for some of these. We'll still error at install-time when the conflicting groups are selected. Due to the likelihood of bugs in this feature, I've marked it as a preview feature. I would not recommend reading the commits as there's some slop from not wanting to rebase Andrew's branch. --------- Co-authored-by: Andrew Gallant <andrew@astral.sh>
76 lines
2.6 KiB
Markdown
76 lines
2.6 KiB
Markdown
# Preview features
|
|
|
|
uv includes opt-in preview features to provide an opportunity for community feedback and increase
|
|
confidence that changes are a net-benefit before enabling them for everyone.
|
|
|
|
## Enabling preview features
|
|
|
|
To enable all preview features, use the `--preview` flag:
|
|
|
|
```console
|
|
$ uv run --preview ...
|
|
```
|
|
|
|
Or, set the `UV_PREVIEW` environment variable:
|
|
|
|
```console
|
|
$ UV_PREVIEW=1 uv run ...
|
|
```
|
|
|
|
To enable specific preview features, use the `--preview-features` flag:
|
|
|
|
```console
|
|
$ uv run --preview-features foo ...
|
|
```
|
|
|
|
The `--preview-features` flag can be repeated to enable multiple features:
|
|
|
|
```console
|
|
$ uv run --preview-features foo --preview-features bar ...
|
|
```
|
|
|
|
Or, features can be provided in a comma separated list:
|
|
|
|
```console
|
|
$ uv run --preview-features foo,bar ...
|
|
```
|
|
|
|
The `UV_PREVIEW_FEATURES` environment variable can be used similarly, e.g.:
|
|
|
|
```console
|
|
$ UV_PREVIEW_FEATURES=foo,bar uv run ...
|
|
```
|
|
|
|
For backwards compatibility, enabling preview features that do not exist will warn, but not error.
|
|
|
|
## Using preview features
|
|
|
|
Often, preview features can be used without changing any preview settings if the behavior change is
|
|
gated by some sort of user interaction, For example, while `pylock.toml` support is in preview, you
|
|
can use `uv pip install` with a `pylock.toml` file without additional configuration because
|
|
specifying the `pylock.toml` file indicates you want to use the feature. However, a warning will be
|
|
displayed that the feature is in preview. The preview feature can be enabled to silence the warning.
|
|
|
|
Other preview features change behavior without changes to your use of uv. For example, when the
|
|
`python-upgrade` feature is enabled, the default behavior of `uv python install` changes to allow uv
|
|
to upgrade Python versions transparently. This feature requires enabling the preview flag for proper
|
|
usage.
|
|
|
|
## Available preview features
|
|
|
|
The following preview features are available:
|
|
|
|
- `add-bounds`: Allows configuring the
|
|
[default bounds for `uv add`](../reference/settings.md#add-bounds) invocations.
|
|
- `json-output`: Allows `--output-format json` for various uv commands.
|
|
- `package-conflicts`: Allows defining workspace conflicts at the package level.
|
|
- `pylock`: Allows installing from `pylock.toml` files.
|
|
- `python-install-default`: Allows
|
|
[installing `python` and `python3` executables](./python-versions.md#installing-python-executables).
|
|
- `python-upgrade`: Allows
|
|
[transparent Python version upgrades](./python-versions.md#upgrading-python-versions).
|
|
|
|
## Disabling preview features
|
|
|
|
The `--no-preview` option can be used to disable preview features.
|