From 71f079853604252c730a322ff38b0e28d2b4a025 Mon Sep 17 00:00:00 2001 From: Zanie Blue Date: Mon, 27 Jan 2025 13:29:23 -0600 Subject: [PATCH] Add a troubleshooting section and reproducible example guide (#10947) Co-authored-by: Ed Morley <501702+edmorley@users.noreply.github.com> --- docs/getting-started/help.md | 5 + .../build-failures.md} | 12 +- docs/reference/troubleshooting/index.md | 7 + .../troubleshooting/reproducible-examples.md | 151 ++++++++++++++++++ mkdocs.template.yml | 6 +- 5 files changed, 174 insertions(+), 7 deletions(-) rename docs/reference/{build_failures.md => troubleshooting/build-failures.md} (96%) create mode 100644 docs/reference/troubleshooting/index.md create mode 100644 docs/reference/troubleshooting/reproducible-examples.md diff --git a/docs/getting-started/help.md b/docs/getting-started/help.md index ac0c0f631..67b15ae29 100644 --- a/docs/getting-started/help.md +++ b/docs/getting-started/help.md @@ -49,6 +49,11 @@ $ uv -V # Will not include the build commit and date $ uv pip --version # Can be used with a subcommand ``` +## Troubleshooting issues + +The reference documentation contains a +[troubleshooting guide](../reference/troubleshooting/index.md) for common issues. + ## Open an issue on GitHub The [issue tracker](https://github.com/astral-sh/uv/issues) on GitHub is a good place to report bugs diff --git a/docs/reference/build_failures.md b/docs/reference/troubleshooting/build-failures.md similarity index 96% rename from docs/reference/build_failures.md rename to docs/reference/troubleshooting/build-failures.md index a919cc161..1f3df8a4e 100644 --- a/docs/reference/build_failures.md +++ b/docs/reference/troubleshooting/build-failures.md @@ -79,7 +79,7 @@ ModuleNotFoundError: No module named 'distutils' !!! important The `--use-pep517` flag should be included with the `pip install` invocation to ensure the same - build isolation behavior. uv always uses [build isolation by default](../pip/compatibility.md#pep-517-build-isolation). + build isolation behavior. uv always uses [build isolation by default](../../pip/compatibility.md#pep-517-build-isolation). We also recommend including the `--force-reinstall` and `--no-cache` options when reproducing failures. @@ -210,7 +210,7 @@ installed. ### Module is missing or cannot be imported If the build error mentions a failing import, consider -[disabling build isolation](../concepts/projects/config.md#build-isolation). +[disabling build isolation](../../concepts/projects/config.md#build-isolation). For example, some packages assume that `pip` is available without declaring it as a build dependency: @@ -258,7 +258,7 @@ dependencies of the package, e.g, `setuptools`. ### Old version of the package is built If a package fails to build during resolution and the version that failed to build is older than the -version you want to use, try adding a [constraint](./settings.md#constraint-dependencies) with a +version you want to use, try adding a [constraint](../settings.md#constraint-dependencies) with a lower bound (e.g. `numpy>=1.17`). Sometimes, due to algorithmic limitations, the uv resolver tries to find a fitting version using unreasonably old packages, which can be prevented by using lower bounds. @@ -286,12 +286,12 @@ Adding a lower bound constraint, e.g., `apache-beam<=2.49.0,>2.30.0`, resolves t uv will avoid using an old version of `apache-beam`. Constraints can also be defined for indirect dependencies using `constraints.txt` files or the -[`constraint-dependencies`](./settings.md#constraint-dependencies) setting. +[`constraint-dependencies`](../settings.md#constraint-dependencies) setting. ### Package is only needed for an unused platform If locking fails due to building a package from a platform you do not need to support, consider -[limiting resolution](../concepts/projects/config.md#limited-resolution-environments) to your +[limiting resolution](../../concepts/projects/config.md#limited-resolution-environments) to your supported platforms. ### Package does not support all Python versions @@ -309,6 +309,6 @@ numpy<1.23; python_version < "3.10" ### Package is only usable on a specific platform If locking fails due to building a package that is only usable on another platform, you can -[provide dependency metadata manually](./settings.md#dependency-metadata) to skip the build. uv can +[provide dependency metadata manually](../settings.md#dependency-metadata) to skip the build. uv can not verify this information, so it is important to specify correct metadata when using this override. diff --git a/docs/reference/troubleshooting/index.md b/docs/reference/troubleshooting/index.md new file mode 100644 index 000000000..5ff82a527 --- /dev/null +++ b/docs/reference/troubleshooting/index.md @@ -0,0 +1,7 @@ +# Troubleshooting + +The troubleshooting section provides information about investigating failures in uv: + +- [Build failures](./build-failures.md): Understanding common causes of package build failures. +- [Reproducible examples](./reproducible-examples.md): How to write a minimal reproducible example + for a uv issue. diff --git a/docs/reference/troubleshooting/reproducible-examples.md b/docs/reference/troubleshooting/reproducible-examples.md new file mode 100644 index 000000000..b21b9c0f7 --- /dev/null +++ b/docs/reference/troubleshooting/reproducible-examples.md @@ -0,0 +1,151 @@ +# Reproducible examples + +## Why reproducible examples are important + +A minimal reproducible example (MRE) is essential for fixing bugs. Without an example that can be +used to reproduce the problem, a maintainer cannot debug it or test if it is fixed. If the example +is not minimal, i.e., if it includes lots of content which is not related to the issue, it can take +a maintainer much longer to identify the root cause of the problem. + +## How to write a reproducible example + +When writing a reproducible examaple, the goal is to provide all of the context necessary for +someone else to reproduce your example. This includes: + +- The platform you're using (e.g., the operating system and architecture) +- Any relevant system state (e.g., ) +- The version of uv +- The version of other relevant tools +- The relevant files (the `uv.lock`, `pyproject.toml`, etc.) +- The commands to run + +To ensure your reproduction is minimal, remove as many dependencies, settings, and files as +possible. Be sure to test your reproduction before sharing it. We recommend including verbose logs +from your reproduction; they may differ on your machine in a critical way. Using a +[Gist](https://gist.github.com) can be helpful for very long logs. + +Below, we'll cover several specific [strategies](#strategies-for-reproducible-examples) for creating +and sharing reproducible examples. + +!!! tip + + There's a great guide to the basics of creating MREs on + [Stack Overflow](https://stackoverflow.com/help/minimal-reproducible-example). + +## Strategies for reproducible examples + +### Docker image + +Writing a Docker image is often the best way to share a reproducible example because it is entirely +self-contained. This means that the state from the reproducer's system does not affect the problem. + +!!! note + + Using a Docker image is only feasible if the issue is reproducible on Linux. When using macOS, + it's prudent to ensure your image is not reproducible on Linux but some bugs _are_ specific + to the operating system. While using Docker to run Windows containers is feasible, it's not + commonplace. These sorts of bugs are expected to be reported as a [script](#script) instead. + +When writing a Docker MRE with uv, it's best to start with one of +[uv's Docker images](../../guides/integration/docker.md#available-images). When doing so, be sure to +pin to a specific version of uv. + +```Dockerfile +FROM ghcr.io/astral-sh/uv:0.5.24-debian-slim +``` + +While Docker images are isolated from the system, the build will use your system's architecture by +default. When sharing a reproduction, you can explicitly set the platform to ensure a reproducer +gets the expected behavior. uv publishes images for `linux/amd64` (e.g., Intel or AMD) and +`linux/arm64` (e.g., Apple M Series or ARM) + +```Dockerfile +FROM --platform=linux/amd64 ghcr.io/astral-sh/uv:0.5.24-debian-slim +``` + +Docker images are best for reproducing issues that can be constructed with commands, e.g.: + +```Dockerfile +FROM --platform=linux/amd64 ghcr.io/astral-sh/uv:0.5.24-debian-slim + +RUN uv init /mre +WORKDIR /mre +RUN uv add pydantic +RUN uv sync +RUN uv run -v python -c "import pydantic" +``` + +However, you can also write files into the image inline: + +```Dockerfile +FROM --platform=linux/amd64 ghcr.io/astral-sh/uv:0.5.24-debian-slim + +COPY </.git +$ cd +$ git checkout +$ +``` + +You can quickly create a new repository in the [GitHub UI](https://github.com/new) or with the `gh` +CLI: + +```console +$ gh repo create uv-mre-1234 --clone +``` + +When using a Git repository for a reproduction, please remember to _minimize_ the contents by +excluding files or settings that are not required to reproduce your problem. diff --git a/mkdocs.template.yml b/mkdocs.template.yml index ef1ca20d3..7294c0f08 100644 --- a/mkdocs.template.yml +++ b/mkdocs.template.yml @@ -70,6 +70,7 @@ plugins: "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" extra_css: - stylesheets/extra.css extra_javascript: @@ -148,7 +149,10 @@ nav: - reference/index.md - Commands: reference/cli.md - Settings: reference/settings.md - - Build failures: reference/build_failures.md + - Troubleshooting: + - reference/troubleshooting/index.md + - Build failures: reference/troubleshooting/build-failures.md + - Reproducible examples: reference/troubleshooting/reproducible-examples.md - Resolver: reference/resolver-internals.md - Benchmarks: reference/benchmarks.md - Policies: