diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 714badc6..5c9fb092 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -83,8 +83,9 @@ In the activated environment, run the app from the repository root:
 python PyReconstruct/run.py
 ```
 
-Alternatively, `pip install -e .` installs the package in editable mode and
-provides the `PyReconstruct` console command (the entry point declared in
+Alternatively, `pip install -e .` (or `uv pip install -e .` in a Python 3.11
+`uv venv` — see [docs/DEV_UV.md](docs/DEV_UV.md)) installs the package in editable
+mode and provides the `PyReconstruct` console command (the entry point declared in
 `pyproject.toml`, `PyReconstruct.cli:main`).
 
 ---
diff --git a/README.md b/README.md
index 05f0915e..46df53e3 100644
--- a/README.md
+++ b/README.md
@@ -62,18 +62,33 @@ default.
 ### From source (developers)
 
 To track the latest commits on `main` (this replaces the old in-app "Developer"
-update channel), run a source install rather than a frozen build. In a Python
-3.11 environment — a `venv` or a conda env (the project pins `>=3.11,<3.12`):
+update channel), run a source install rather than a frozen build.
+
+PyReconstruct requires **Python 3.11** — the pinned version the app and its
+native dependencies are validated on (the project pins `>=3.11,<3.12`). Your
+system `python3` is likely newer, and `pip install -e .` will fail against it; the
+steps below get you 3.11 without changing your system Python.
 
 ```
 git clone https://github.com/dustenhubbard/PyReconstruct
 cd PyReconstruct
-pip install -e .          # editable: your working tree IS the running code
-PyReconstruct
+
+# recommended: uv (installs Python 3.11 for you)
+curl -LsSf https://astral.sh/uv/install.sh | sh   # or: brew install uv
+uv venv --python 3.11
+source .venv/bin/activate          # Windows: .venv\Scripts\activate
+uv pip install -e .                # editable: your working tree IS the running code
+
+# alternative: plain venv (requires python3.11 already on PATH)
+python3.11 -m venv .venv && source .venv/bin/activate
+pip install -e .
+
+PyReconstruct                      # launch
 ```
 
 Pull to move to the newest code (`git pull`); because the install is editable,
-the pulled source runs immediately with no reinstall. You can also update from
+the pulled source runs immediately with no reinstall — rerun the editable install
+only when `pyproject.toml` changes. You can also update from
 inside the app — **Help ▸ Check for updates** on a source install reinstalls the
 branch set under **Series ▸ Options ▸ Updates** (default `main`) with `pip` — or
 from the command line with `PyReconstruct --update` (`PyReconstruct --switch
diff --git a/docs/USER_GUIDE.md b/docs/USER_GUIDE.md
index 9127e4fc..54aa3457 100644
--- a/docs/USER_GUIDE.md
+++ b/docs/USER_GUIDE.md
@@ -89,15 +89,25 @@ Mac its matching architecture.
 
 ### From source (Linux, other platforms, and developers)
 
-In a Python 3.11 environment (the project pins `>=3.11,<3.12`):
+PyReconstruct requires **Python 3.11** — the pinned version the app and its
+native dependencies are validated on (the project pins `>=3.11,<3.12`). Your
+system `python3` is likely newer, and installing against it will fail; the steps
+below get you 3.11 without changing your system Python. The recommended tool is
+[uv](https://docs.astral.sh/uv/), which downloads Python 3.11 for you — install
+it with `curl -LsSf https://astral.sh/uv/install.sh | sh` (or `brew install uv`).
+
+For a quick, non-editable install into a fresh 3.11 environment:
 
 ```
-pip install git+https://github.com/dustenhubbard/PyReconstruct
+uv venv --python 3.11 && source .venv/bin/activate   # Windows: .venv\Scripts\activate
+uv pip install git+https://github.com/dustenhubbard/PyReconstruct
 PyReconstruct
 ```
 
 `pip` pulls in the runtime dependencies (PySide6, VTK, vedo, NumPy, SciPy,
-scikit-image, shapely, trimesh, zarr, and others).
+scikit-image, shapely, trimesh, zarr, and others). If you already have
+`python3.11` on PATH, plain `venv` works instead of `uv`: `python3.11 -m venv
+.venv && source .venv/bin/activate`, then `pip install git+…`.
 
 To **track the latest unreleased code on `main`** (what the retired in-app
 "Developer" channel used to offer), clone the repository and install it editable,
@@ -106,8 +116,18 @@ then `git pull` whenever you want the newest commits:
 ```
 git clone https://github.com/dustenhubbard/PyReconstruct
 cd PyReconstruct
-pip install -e .          # editable: the checkout IS the running code
-git pull                  # later, to move to the newest main; no reinstall needed
+
+# recommended: uv (installs Python 3.11 for you)
+uv venv --python 3.11
+source .venv/bin/activate          # Windows: .venv\Scripts\activate
+uv pip install -e .                # editable: the checkout IS the running code
+
+# alternative: plain venv (requires python3.11 already on PATH)
+python3.11 -m venv .venv && source .venv/bin/activate
+pip install -e .
+
+git pull                           # later, to move to the newest main; rerun the
+                                   # editable install only when pyproject.toml changes
 ```
 
 For a full development setup (the conda `pyrecon_dev` environment, tests, code