diff --git a/package-structure-code/declare-dependencies.md b/package-structure-code/declare-dependencies.md
index e18a5a5a1..0ae0c8c76 100644
--- a/package-structure-code/declare-dependencies.md
+++ b/package-structure-code/declare-dependencies.md
@@ -307,6 +307,13 @@ uv sync --group docs                     # Single group
 uv sync --group docs --group test        # Multiple groups
 uv sync --all-groups                     # All dependency groups
 ```
+:::{tip}
+use ``--active`` with ``uv sync`` to prefer the currently active virtual environment over the project's own managed environment:
+
+```console
+$ uv sync --active --group docs
+```
+:::
 
 **Install optional dependencies:**
 
@@ -316,6 +323,20 @@ $ uv pip install -e ".[docs]"              # Single group
 $ uv pip install -e ".[docs,tests,lint]"   # Multiple groups
 ```
 
+:::{tip}
+Use the `--active` flag with `uv run` to prefer the currently active
+virtual environment over the project's own managed environment:
+
+```console
+$ uv run --active pip install -e ".[docs]"
+```
+:::
+
+This is useful when you have activated a virtual environment and want
+`uv run` to use it instead of automatically creating or selecting the
+project's environment.
+:::
+
 **Install everything (package + all dependencies):**
 
 ```console