From 9f53c5866f7e2fa47ccb4f231772dfd35ce635f1 Mon Sep 17 00:00:00 2001
From: Charlie Marsh <charlie.r.marsh@gmail.com>
Date: Thu, 5 Mar 2026 16:18:01 -0500
Subject: [PATCH] Add documentation for common marker values (#18327)

Closes https://github.com/astral-sh/uv/issues/18300.
---
 crates/uv-workspace/src/pyproject.rs |  8 ++++++--
 docs/concepts/resolution.md          | 30 ++++++++++++++++++++++++++++
 2 files changed, 36 insertions(+), 2 deletions(-)

diff --git a/crates/uv-workspace/src/pyproject.rs b/crates/uv-workspace/src/pyproject.rs
index 3775e56ad..27b70271c 100644
--- a/crates/uv-workspace/src/pyproject.rs
+++ b/crates/uv-workspace/src/pyproject.rs
@@ -649,10 +649,14 @@ pub struct ToolUv {
         default = "[]",
         value_type = "str | list[str]",
         example = r#"
-            # Require that the package is available for macOS ARM and x86 (Intel).
+            # Require that the package is available on the following platforms:
             required-environments = [
+                # macOS on Apple Silicon (ARM)
                 "sys_platform == 'darwin' and platform_machine == 'arm64'",
-                "sys_platform == 'darwin' and platform_machine == 'x86_64'",
+                # Linux on x86_64 (Intel/AMD)
+                "sys_platform == 'linux' and platform_machine == 'x86_64'",
+                # Windows on x86_64 (Intel/AMD)
+                "sys_platform == 'win32' and platform_machine == 'AMD64'",
             ]
         "#
     )]
diff --git a/docs/concepts/resolution.md b/docs/concepts/resolution.md
index 2d3778eea..38e9cd637 100644
--- a/docs/concepts/resolution.md
+++ b/docs/concepts/resolution.md
@@ -216,6 +216,36 @@ required-environments = [
 ]
 ```
 
+## Common marker values
+
+The `environments` and `required-environments` settings accept
+[PEP 508 environment markers](https://packaging.python.org/en/latest/specifications/dependency-specifiers/#environment-markers).
+The values for these markers are derived from the Python runtime (e.g.,
+[`sys.platform`](https://docs.python.org/3/library/sys.html#sys.platform),
+[`platform.machine()`](https://docs.python.org/3/library/platform.html#platform.machine),
+[`platform.system()`](https://docs.python.org/3/library/platform.html#platform.system), and
+[`os.name`](https://docs.python.org/3/library/os.html#os.name)).
+
+For quick reference, the most common marker values by platform are:
+
+| Marker                      | Linux       | macOS      | Windows     |
+| --------------------------- | ----------- | ---------- | ----------- |
+| `sys_platform`              | `'linux'`   | `'darwin'` | `'win32'`   |
+| `platform_system`           | `'Linux'`   | `'Darwin'` | `'Windows'` |
+| `platform_machine` (x86-64) | `'x86_64'`  | `'x86_64'` | `'AMD64'`   |
+| `platform_machine` (ARM64)  | `'aarch64'` | `'arm64'`  | `'ARM64'`   |
+| `os_name`                   | `'posix'`   | `'posix'`  | `'nt'`      |
+
+!!! note
+
+    On Windows, `sys_platform` is always `'win32'`, even on 64-bit systems.
+
+You can check the values for your current platform by running:
+
+```console
+$ uvx python -c "import sysconfig; print(sysconfig.get_config_vars())"
+```
+
 ## Dependency preferences
 
 If resolution output file exists, i.e., a uv lockfile (`uv.lock`) or a requirements output file