mirror of
https://github.com/astral-sh/uv.git
synced 2026-05-06 08:56:53 -04:00
Aria Desires
202e0f0831
## Summary This expands `uv workspace metadata` with many of the fields that are found in `uv.lock` so that we have a format with information about the dependency graph/resolution that we're willing to call stable and have people rely upon (rather than `uv.lock` which we'd rather you don't try to interpret). To a first approximation you can think of this as "uv.lock but serialized to json" but with the fields a bit more limited for now (easy to add later). The biggest intentional divergence with uv.lock is that we favour encoding the dependency graph in a form that looks more like our internal "resolve" graph, in that hopes that it will simplify the work of anyone doing analysis on the graph (we structure our internal graph like this for a reason). Specifically, the `resolve` field contains the entire dependency graph, with packages desugarred into several different nodes. There are 4 kinds of nodes (really 3, the build nodes will only be introduced when we establish build-dependency locking): * packages: `mypackage==1.0.0 @ registry+https://pypi.org/simple` * extras: `mypackage[myextra]==1.0.0 @ registry+https://pypi.org/simple` * groups: `mypackage:mygroup==1.0.0 @ registry+https://pypi.org/simple` * build: `mypackage(build)==1.0.0 @ registry+https://pypi.org/simple` package nodes hold additional metadata about the package itself, and ids of the associated extra/group/build nodes. --- A package like this: ```toml [project] name = "mypackage" version = "1.0.0" dependencies = ["httpx"] [project.optional-dependencies] cli = ["rich"] [dependency-groups] dev = ["typing-extensions"] [build-system] requires = ["hatchling"] build-backend = "hatchling.build" ``` will get 4 nodes with the following edges (Version and Source omitted here for brevity): * `mypackage` * `httpx` * `mypackage(build)` * `hatchling` * `mypackage[cli]` * `mypackage` * `rich` * `mypackage:dev` * `typing-extensions` Note that `mypackage[cli]` has a dependency edge on `mypackage` while `mypackage:dev` does not. This is because `mypackage[cli]` is fundamentally an augmentation of `mypackage` while `mypackage:dev` is just a list of packages that happens to be defined by `mypackage`'s pyproject.toml. The resulting nodes for `mypackage` will look something like: <details> <summary>json blob</summary> ```json { "resolve": { "mypackage==1.0.0 @ editable+.": { "name": "mypackage", "version": "1.0.0", "source": { "editable": "." }, "kind": "package", "dependencies": [ { "id": "httpx==3.6 @ registry+https://pypi.org/simple" "marker": "sys_platform == 'linux'" }, ], "optional_dependencies": [ { "name": "cli", "id": "mypackage[cli]==1.0.0 @ editable+." }, ], "dependency_groups": [ { "name": "dev", "id": "mypackage:dev==1.0.0 @ editable+." } ] "build_system": { "build_backend": "hatchling.build", "id": "mypackage(build)==1.0.0 @ editable+." } "sdist": { ... }, "wheels": [ ... ] }, "mypackage:dev==1.0.0 @ editable+.": { "name": "mypackage", "version": "1.0.0", "source": { "editable": "." }, "kind": { "group": "dev" }, "dependencies": [ { "id": "typing-extensions==1.2.3 @ registry+https://pypi.org/simple" }, ] }, } "mypackage[cli]==1.0.0 @ editable+.": { "name": "mypackage", "version": "1.0.0", "source": { "editable": "." }, "kind": { "extra": "cli" }, "dependencies": [ { "id": "rich==2.2.3 @ registry+https://pypi.org/simple" }, { "id": "mypackage==1.0.0 @ editable+." }, ] }, "mypackage(build)==1.0.0 @ editable+.": { "name": "mypackage", "version": "1.0.0", "source": { "editable": "." }, "kind": "build", "dependencies": [ { "id": "hatchling==3.2.3 @ registry+https://pypi.org/simple" }, ] } } } ``` </details> ## Test Plan Snapshots
279 lines
11 KiB
YAML
279 lines
11 KiB
YAML
site_name: uv
|
|
theme:
|
|
name: material
|
|
logo: assets/logo-letter.svg
|
|
favicon: assets/favicon.ico
|
|
features:
|
|
- navigation.path
|
|
- navigation.instant
|
|
- navigation.instant.prefetch
|
|
- navigation.instant.progress
|
|
- navigation.sections
|
|
- navigation.indexes
|
|
- navigation.tracking
|
|
- content.code.annotate
|
|
- toc.follow
|
|
- navigation.footer
|
|
- navigation.top
|
|
- content.code.copy
|
|
- content.tabs.link
|
|
palette:
|
|
# Note: Using the system theme works with the insiders version
|
|
# https://squidfunk.github.io/mkdocs-material/setup/changing-the-colors/#automatic-light-dark-mode
|
|
- media: "(prefers-color-scheme)"
|
|
toggle:
|
|
icon: material/brightness-auto
|
|
name: Switch to light mode
|
|
- media: "(prefers-color-scheme: light)"
|
|
scheme: astral-light
|
|
toggle:
|
|
icon: material/brightness-7
|
|
name: Switch to dark mode
|
|
- media: "(prefers-color-scheme: dark)"
|
|
scheme: astral-dark
|
|
toggle:
|
|
icon: material/brightness-4
|
|
name: Switch to system preference
|
|
custom_dir: docs/.overrides
|
|
repo_url: https://github.com/astral-sh/uv
|
|
repo_name: uv
|
|
site_author: charliermarsh
|
|
site_url: https://docs.astral.sh/uv/
|
|
site_dir: site/uv
|
|
site_description: uv is an extremely fast Python package and project manager, written in Rust.
|
|
markdown_extensions:
|
|
- admonition
|
|
- pymdownx.details
|
|
- pymdownx.snippets:
|
|
- pymdownx.magiclink:
|
|
- attr_list:
|
|
- toc:
|
|
anchorlink: true
|
|
anchorlink_class: "toclink"
|
|
- md_in_html:
|
|
- pymdownx.inlinehilite:
|
|
- pymdownx.superfences:
|
|
- markdown.extensions.attr_list:
|
|
- pymdownx.keys:
|
|
- pymdownx.tasklist:
|
|
custom_checkbox: true
|
|
- pymdownx.highlight:
|
|
anchor_linenums: true
|
|
- pymdownx.tabbed:
|
|
alternate_style: true
|
|
plugins:
|
|
- search
|
|
- git-revision-date-localized:
|
|
timezone: UTC # It can only be in UTC unless the ISO time can include timezone.
|
|
- redirects:
|
|
# Note that redirecting an anchor, e.g., `concepts/projects/#managing-dependencies` must be done
|
|
# client-side and is implemented in `extra.js` instead.
|
|
redirect_maps:
|
|
"guides/publish.md": "guides/package.md"
|
|
"concepts/workspaces.md": "concepts/projects/workspaces.md"
|
|
"concepts/dependencies.md": "concepts/projects/dependencies.md"
|
|
"reference/versioning.md": "reference/policies/versioning.md"
|
|
"reference/platforms.md": "reference/policies/platforms.md"
|
|
"reference/build_failures.md": "reference/troubleshooting/build-failures.md"
|
|
"reference/resolver-internals.md": "reference/internals/resolver.md"
|
|
"configuration/installer.md": "reference/installer.md"
|
|
"configuration/authentication.md": "concepts/authentication/index.md"
|
|
"configuration/build-backend.md": "concepts/build-backend.md"
|
|
"configuration/files.md": "concepts/configuration-files.md"
|
|
"configuration/indexes.md": "concepts/indexes.md"
|
|
"configuration/environment.md": "reference/environment.md"
|
|
"guides/export.md": "concepts/projects/export.md"
|
|
"guides/integration/dependency-bots.md": "guides/integration/renovate.md"
|
|
"guides/integration/alternative-indexes.md": "concepts/authentication/third-party.md"
|
|
- llmstxt:
|
|
markdown_description: |
|
|
You can use uv to install Python dependencies, run scripts, manage virtual environments,
|
|
build and publish packages, and even install Python itself. uv is capable of replacing
|
|
`pip`, `pip-tools`, `pipx`, `poetry`, `pyenv`, `twine`, `virtualenv`, and more.
|
|
|
|
uv includes both a pip-compatible CLI (prepend `uv` to a pip command, e.g., `uv pip install ruff`)
|
|
and a first-class project interface (e.g., `uv add ruff`) complete with lockfiles and
|
|
workspace support.
|
|
|
|
When fetching documentation, use explicit `index.md` paths for directories, e.g.,
|
|
`https://docs.astral.sh/uv/concepts/projects/dependencies/index.md`. This returns
|
|
clean markdown instead of rendered HTML with JS/CSS.
|
|
sections:
|
|
Getting started:
|
|
- getting-started/installation.md
|
|
- getting-started/first-steps.md
|
|
- getting-started/features.md
|
|
Guides:
|
|
- guides/install-python.md
|
|
- guides/scripts.md
|
|
- guides/tools.md
|
|
- guides/projects.md
|
|
- guides/package.md
|
|
Integrations:
|
|
- guides/integration/docker.md
|
|
- guides/integration/jupyter.md
|
|
- guides/integration/marimo.md
|
|
- guides/integration/github.md
|
|
- guides/integration/gitlab.md
|
|
- guides/integration/pre-commit.md
|
|
- guides/integration/pytorch.md
|
|
- guides/integration/fastapi.md
|
|
- guides/integration/azure.md
|
|
- guides/integration/google.md
|
|
- guides/integration/aws.md
|
|
- guides/integration/jfrog.md
|
|
- guides/integration/renovate.md
|
|
- guides/integration/dependabot.md
|
|
- guides/integration/aws-lambda.md
|
|
- guides/integration/coiled.md
|
|
Projects:
|
|
- concepts/projects/layout.md
|
|
- concepts/projects/init.md
|
|
- concepts/projects/dependencies.md
|
|
- concepts/projects/run.md
|
|
- concepts/projects/sync.md
|
|
- concepts/projects/config.md
|
|
- concepts/projects/build.md
|
|
- concepts/projects/export.md
|
|
- concepts/projects/workspaces.md
|
|
Features:
|
|
- concepts/tools.md
|
|
- concepts/python-versions.md
|
|
- concepts/configuration-files.md
|
|
- concepts/indexes.md
|
|
- concepts/resolution.md
|
|
- concepts/build-backend.md
|
|
- concepts/authentication/index.md
|
|
- concepts/cache.md
|
|
- concepts/preview.md
|
|
The pip interface:
|
|
- pip/environments.md
|
|
- pip/packages.md
|
|
- pip/inspection.md
|
|
- pip/dependencies.md
|
|
- pip/compile.md
|
|
- pip/compatibility.md
|
|
Reference:
|
|
- reference/cli.md
|
|
- reference/settings.md
|
|
- reference/storage.md
|
|
- reference/environment.md
|
|
- reference/installer.md
|
|
extra_css:
|
|
- stylesheets/extra.css
|
|
extra_javascript:
|
|
- js/extra.js
|
|
extra:
|
|
analytics:
|
|
provider: fathom
|
|
social:
|
|
- icon: fontawesome/brands/github
|
|
link: https://github.com/astral-sh/uv
|
|
- icon: fontawesome/brands/discord
|
|
link: https://discord.com/invite/astral-sh
|
|
- icon: fontawesome/brands/python
|
|
link: https://pypi.org/project/uv/
|
|
- icon: fontawesome/brands/x-twitter
|
|
link: https://x.com/astral_sh
|
|
nav:
|
|
- Introduction: index.md
|
|
- Getting started:
|
|
- getting-started/index.md
|
|
- Installation: getting-started/installation.md
|
|
- First steps: getting-started/first-steps.md
|
|
- Features: getting-started/features.md
|
|
- Getting help: getting-started/help.md
|
|
- Guides:
|
|
- guides/index.md
|
|
- Installing Python: guides/install-python.md
|
|
- Running scripts: guides/scripts.md
|
|
- Using tools: guides/tools.md
|
|
- Working on projects: guides/projects.md
|
|
- Publishing packages: guides/package.md
|
|
- Migration:
|
|
- guides/migration/index.md
|
|
- From pip to a uv project: guides/migration/pip-to-project.md
|
|
- Integrations:
|
|
- guides/integration/index.md
|
|
- Docker: guides/integration/docker.md
|
|
- Jupyter: guides/integration/jupyter.md
|
|
- marimo: guides/integration/marimo.md
|
|
- GitHub Actions: guides/integration/github.md
|
|
- GitLab CI/CD: guides/integration/gitlab.md
|
|
- Pre-commit: guides/integration/pre-commit.md
|
|
- PyTorch: guides/integration/pytorch.md
|
|
- FastAPI: guides/integration/fastapi.md
|
|
- Azure Artifacts: guides/integration/azure.md
|
|
- Google Artifact Registry: guides/integration/google.md
|
|
- AWS CodeArtifact: guides/integration/aws.md
|
|
- JFrog Artifactory: guides/integration/jfrog.md
|
|
- Renovate: guides/integration/renovate.md
|
|
- Dependabot: guides/integration/dependabot.md
|
|
- AWS Lambda: guides/integration/aws-lambda.md
|
|
- Coiled: guides/integration/coiled.md
|
|
- Concepts:
|
|
- concepts/index.md
|
|
- Projects:
|
|
- concepts/projects/index.md
|
|
- Structure and files: concepts/projects/layout.md
|
|
- Creating projects: concepts/projects/init.md
|
|
- Managing dependencies: concepts/projects/dependencies.md
|
|
- Running commands: concepts/projects/run.md
|
|
- Locking and syncing: concepts/projects/sync.md
|
|
- Configuring projects: concepts/projects/config.md
|
|
- Building distributions: concepts/projects/build.md
|
|
- Exporting lockfiles: concepts/projects/export.md
|
|
- Using workspaces: concepts/projects/workspaces.md
|
|
- Tools: concepts/tools.md
|
|
- Python versions: concepts/python-versions.md
|
|
- Configuration files: concepts/configuration-files.md
|
|
- Package indexes: concepts/indexes.md
|
|
- Resolution: concepts/resolution.md
|
|
- Build backend: concepts/build-backend.md
|
|
- Authentication:
|
|
- concepts/authentication/index.md
|
|
- The auth CLI: concepts/authentication/cli.md
|
|
- HTTP credentials: concepts/authentication/http.md
|
|
- Git credentials: concepts/authentication/git.md
|
|
- TLS certificates: concepts/authentication/certificates.md
|
|
- Third-party services: concepts/authentication/third-party.md
|
|
- Caching: concepts/cache.md
|
|
- Preview features: concepts/preview.md
|
|
# Note: The `pip` section was moved to the `concepts/` section but the
|
|
# top-level directory structure was retained to ease the transition.
|
|
- The pip interface:
|
|
- pip/index.md
|
|
- Using environments: pip/environments.md
|
|
- Managing packages: pip/packages.md
|
|
- Inspecting environments: pip/inspection.md
|
|
- Declaring dependencies: pip/dependencies.md
|
|
- Locking environments: pip/compile.md
|
|
- Compatibility with pip: pip/compatibility.md
|
|
- Reference:
|
|
- reference/index.md
|
|
- Commands: reference/cli.md
|
|
- Settings: reference/settings.md
|
|
- Environment variables: reference/environment.md
|
|
- Storage: reference/storage.md
|
|
- Installer options: reference/installer.md
|
|
- Troubleshooting:
|
|
- reference/troubleshooting/index.md
|
|
- Build failures: reference/troubleshooting/build-failures.md
|
|
- Reproducible examples: reference/troubleshooting/reproducible-examples.md
|
|
- Internals:
|
|
- reference/internals/index.md
|
|
- Resolver: reference/internals/resolver.md
|
|
- Workspace Metadata: reference/internals/metadata.md
|
|
- Benchmarks: reference/benchmarks.md
|
|
- Policies:
|
|
- reference/policies/index.md
|
|
- Versioning: reference/policies/versioning.md
|
|
- Platform support: reference/policies/platforms.md
|
|
- Python support: reference/policies/python.md
|
|
- Rust support: reference/policies/rust.md
|
|
- License: reference/policies/license.md
|
|
validation:
|
|
omitted_files: warn
|
|
absolute_links: warn
|
|
unrecognized_links: warn
|