Docs: Clarify that uv run syncs dev dependencies by default and how to prevent it

crates/uv-cli/src/lib.rs

@@ -1062,6 +1062,10 @@ pub enum ProjectCommand {
     /// When used in a project, the project environment will be created and updated before invoking
     /// the command.
     ///
+    /// By default, this environment is synced with development dependencies. To prevent development
+    /// dependencies from being installed (e.g., in a production environment), use the `--no-dev`
+    /// flag, use the `--no-sync` flag, or set `UV_NO_DEV=1`.
+    ///
     /// When used outside a project, if a virtual environment can be found in the current directory
     /// or a parent directory, the command will be run in that environment. Otherwise, the command
     /// will be run in the environment of the discovered interpreter.
@@ -1186,6 +1190,9 @@ pub enum ProjectCommand {
     /// At present, `requirements.txt`, `pylock.toml` (PEP 751) and CycloneDX v1.5 JSON output
     /// formats are supported.
     ///
+    /// By default, the exported requirements include the project's default dependency groups
+    /// (such as the standard dependencies and the `dev` group).
+    ///
     /// The project is re-locked before exporting unless the `--locked` or `--frozen` flag is
     /// provided.
     ///

docs/concepts/projects/config.md

@@ -542,6 +542,14 @@ version = "2.6.3"
 requires-dist = ["torch", "einops"]
 ```
 
+## Dynamic metadata
+
+If your project uses dynamic metadata (e.g., to determine the version or dependencies dynamically),
+uv may need additional configuration to invalidate its cache when the metadata changes.
+
+See the [caching documentation](../cache.md#dynamic-metadata) for details on configuring cache
+invalidation for dynamic metadata.
+
 ## Editable mode
 
 By default, the project will be installed in editable mode, such that changes to the source code are

docs/concepts/projects/sync.md

@@ -11,6 +11,14 @@ and synced before invoking the requested command. This ensures the project envir
 up-to-date. Similarly, commands which read the lockfile, such as `uv tree`, will automatically
 update it before running.
 
+!!! tip "Syncing in production environments"
+
+    Because `uv run` automatically syncs the environment and includes development dependencies by default,
+    it may inadvertently install development dependencies when used in production.
+
+    To avoid this, use the `--no-dev` flag (e.g., `uv run --no-dev ...`), or `--no-sync` if the environment
+    is already prepared (e.g., via an earlier `uv sync --no-dev`). You can also enforce this by setting `UV_NO_SYNC=1` or `UV_NO_DEV=1` in your environment.
+
 To disable automatic locking, use the `--locked` option:
 
 ```console