ivany-nv · Oct 31, 2026 · Oct 28, 2026 · Oct 28, 2026 · Oct 28, 2026 · Oct 28, 2026
diff --git a/docs/source/development/build_from_source/index.rst b/docs/source/development/build_from_source/index.rst
@@ -332,6 +332,8 @@ When ``BUILD_TESTING`` is ``ON``, CTest is enabled at the top level. Run all tes
 
 The CI uses ``ctest`` (see :code-file:`build-ubuntu.yml <.github/workflows/build-ubuntu.yml>`).
 
+.. _build-from-source-install-package:
+
 4. Install the ``isaaccapture`` pip package
 -------------------------------------------
 
@@ -348,6 +350,9 @@ From the repository root:
    uv venv --python 3.11 --seed .venv
    source .venv/bin/activate
 
+If ``.venv`` already exists on the build's Python, activate it and skip ``uv venv``. To switch it
+to another Python, rerun ``uv venv`` with ``--clear``, which deletes everything installed in it.
+
 Install it by version. A local build is always ``X.Y+local``, where ``X.Y`` is the first two
 numbers of the repository's ``VERSION`` file; they also appear in the wheel's file name. The pin
 selects your build for the venv's Python, so a newer published ``isaaccapture`` cannot replace it.
@@ -365,6 +370,13 @@ differently:
    # --reinstall-package replaces an already-installed isaaccapture, e.g. after a rebuild.
    uv pip install "isaaccapture[retargeters,cloudxr,ui]==X.Y+local" --find-links=./install/wheels/ --reinstall-package isaaccapture
 
+.. _build-from-source-editable-examples:
+
+An example whose ``pyproject.toml`` points ``[tool.uv.sources]`` at this checkout replaces this
+wheel with an editable build of the checkout when you install it. Its first install compiles the
+extensions, and uv reuses that build afterwards, so after a C++ change reinstall the example with
+``uv pip install -e ./examples/<name> --reinstall-package isaaccapture``.
+
 The wheel carries the ``isaacteleop`` compatibility alias, which will be removed
 in 1.9, so
 ``import isaacteleop`` resolves without installing anything else. See

diff --git a/docs/source/device/body_tracking/soma.rst b/docs/source/device/body_tracking/soma.rst
@@ -87,19 +87,15 @@ Build the examples
 
 Start with a configured Isaac Capture checkout. See
 :doc:`../../development/build_from_source/index` for the complete build
-prerequisites. Install the live viewer and both deterministic publishers:
+prerequisites. Install the live viewer and both deterministic publishers into a venv
+set up as in :ref:`step 4 of Build from source <build-from-source-install-package>`:
 
 .. code-block:: bash
 
    uv pip install -e ./examples/deviceio_live_view
    uv pip install -e ./examples/soma_body_publisher
    uv pip install -e ./examples/soma_hand_publisher
 
-   .venv/bin/cmake -S . -B build
-   .venv/bin/cmake --build build \
-     --target isaacteleop_python \
-     -j4
-
 The example packages install ``py-soma-x==0.3.1``.
 The publishers use the Python-accessible ``TensorPushTracker`` and its native
 ``SchemaPusher`` transport; no separate sender executable is needed. Demo samples

diff --git a/docs/source/device/hand_tracking/sharpa_avatar.rst b/docs/source/device/hand_tracking/sharpa_avatar.rst
@@ -118,7 +118,8 @@ See :ref:`dedicated-cloudxr-runtime` and
 
 ``TeleopSession`` can launch the same binary through ``plugin.yaml``. The
 visualization example does that for you (CloudXR and the plugin start unless
-you opt out):
+you opt out). Run it from the repository root, in a venv set up as in
+:ref:`step 4 of Build from source <build-from-source-install-package>`:
 
 .. code-block:: bash
 

diff --git a/docs/source/device/trackers/vive_ultimate_tracker.rst b/docs/source/device/trackers/vive_ultimate_tracker.rst
@@ -214,7 +214,8 @@ printer. Use a collection id printed by the plugin in Step 7:
 Step 9 (optional): Record and replay
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Install the examples package once, from the Isaac Capture root:
+Install the examples package once, from the Isaac Capture root, in a venv set up as in
+:ref:`step 4 of Build from source <build-from-source-install-package>`:
 
 .. code-block:: bash
 

diff --git a/docs/source/references/build.rst b/docs/source/references/build.rst
@@ -57,8 +57,8 @@ The project uses a modern CMake target-based approach. Libraries export namespac
 Using the Python wheel
 ----------------------
 
-After building, activate a virtual environment with the build's Python version (step 4 of
-:doc:`/development/build_from_source/index` shows how), then install the wheels with ``uv`` or
+After building, activate a virtual environment with the build's Python version
+(:ref:`step 4 of Build from source <build-from-source-install-package>` shows how), then install the wheels with ``uv`` or
 ``pip``, pinning the local build's version ``X.Y+local`` (``X.Y`` from the repository's ``VERSION``
 file):
 
@@ -69,7 +69,7 @@ file):
    uv pip install "isaaccapture==X.Y+local" --find-links=./install/wheels/ --reinstall-package isaaccapture
 
    # or
-   pip install "isaaccapture==X.Y+local" --find-links=./install/wheels/
+   pip install "isaaccapture==X.Y+local" --find-links=./install/wheels/ --force-reinstall
 
 The wheel carries the ``isaacteleop`` compatibility alias, which will be removed
 in 1.9, so

diff --git a/docs/source/references/camera_streaming.rst b/docs/source/references/camera_streaming.rst
@@ -123,16 +123,24 @@ needs. Flags trim or extend that:
    * - ``--wheel PATH``
      - Install a locally built ``isaaccapture`` wheel instead of resolving one from the index — for
        developing Isaac Capture itself.
+   * - ``--python VERSION``
+     - Python for the venv that ``setup`` creates (default 3.12). An existing ``.venv`` keeps its
+       Python.
    * - ``--build-from-source``
      - Skip the package index and build ``isaaccapture`` from the surrounding checkout without
        prompting — a full C++ / CUDA / Vulkan build (see
        :doc:`/development/build_from_source/index`).
 
-For example, to use a wheel built from this checkout, run from the repository root:
+For example, to use a wheel built from this checkout, run from the repository root. Name one
+wheel: ``install/wheels/`` keeps earlier builds, and ``--wheel`` takes a single path. ``X.Y`` is as
+in :ref:`step 4 of Build from source <build-from-source-install-package>`, and both the wheel's
+``cp`` tag and ``--python`` must match the build's ``ISAAC_TELEOP_PYTHON_VERSION`` (3.11 by
+default):
 
 .. code-block:: bash
 
-   examples/camera_viz/camera_viz.sh setup --wheel build/wheels/isaaccapture-*.whl
+   examples/camera_viz/camera_viz.sh setup --python 3.11 \
+       --wheel install/wheels/isaaccapture-X.Y+local-cp311-cp311-linux_x86_64.whl
 
 .. _camera-streaming-external-venv:
 

diff --git a/docs/source/references/haptic_feedback.rst b/docs/source/references/haptic_feedback.rst
@@ -67,9 +67,8 @@ Running
 
 The example connects through the CloudXR / OpenXR runtime, which it starts
 itself if nothing is serving (see :ref:`dedicated-cloudxr-runtime` to manage
-that service yourself). Install ``isaaccapture`` built from this tree into the
-active environment first, for example
-``uv pip install "isaaccapture[cloudxr]" --find-links=./install/wheels/``.
+that service yourself). From the repository root, set up a venv and install
+``isaaccapture`` into it as in :ref:`step 4 of Build from source <build-from-source-install-package>`.
 Then install the example and run it:
 
 .. code-block:: bash

diff --git a/docs/source/references/mcap_record_replay.rst b/docs/source/references/mcap_record_replay.rst
@@ -156,7 +156,7 @@ additional source nodes (``HeadSource``, ``ControllersSource``, …) in
 
 For a live browser view of **all** human DeviceIO trackers at once (hands, head,
 controllers, and full body), see ``examples/deviceio_live_view/`` and its
-``README.md``:
+``README.md``. From the repo root, in a venv set up as in :ref:`step 4 of Build from source <build-from-source-install-package>`:
 
 .. code-block:: bash
 
@@ -173,7 +173,7 @@ A C++ recorder lives at ``examples/mcap_record_replay/cpp/``:
 Live preview
 ^^^^^^^^^^^^
 
-From the repo root:
+From the repo root, in a venv set up as in :ref:`step 4 of Build from source <build-from-source-install-package>`:
 
 .. code-block:: bash
 
@@ -188,7 +188,7 @@ opened from another machine; pass ``--host 127.0.0.1`` to keep one local.
 Recording
 ^^^^^^^^^
 
-From the repo root:
+From the repo root, in the same venv:
 
 .. code-block:: bash
 
@@ -202,10 +202,10 @@ Recordings are written to ``./recordings/`` relative to where you run the
 command, and the replay scripts look there when given no path.
 
 The example never downloads a published wheel — it runs against the
-``isaaccapture`` next to it, built from this checkout.  The first install
-compiles the extension modules and takes a few minutes; later ones reuse the
-cached build, and the install is editable, so edits under ``src/python/`` need
-no rebuild.  From ``install/examples/mcap_record_replay`` (after ``cmake
+``isaaccapture`` next to it, built from this checkout.  The install is editable,
+so edits under ``src/python/`` need no rebuild; for C++ changes see
+:ref:`step 4 of Build from source <build-from-source-editable-examples>`.  From
+``install/examples/mcap_record_replay`` (after ``cmake
 --install``) it picks up the wheel you just built instead — see
 :doc:`/development/build_from_source/index`.
 
@@ -235,10 +235,6 @@ The ``record_controller`` / ``replay_controller`` and ``record_full_body`` /
 ``--host``, ``--port``). ``live_full_body`` accepts ``--host``,
 ``--port``, and the CloudXR launcher flags (including ``--accept-eula``).
 
-``uv run`` (instead of an activated venv) needs an explicit ``--python 3.11``
-— without it, ``uv`` may resolve against the system Python and fail to match
-the lockfile.
-
 API Reference
 -------------
 

diff --git a/docs/source/references/retargeting/sharpa.rst b/docs/source/references/retargeting/sharpa.rst
@@ -125,7 +125,9 @@ produced in your target joint order.
 Run the example
 ---------------
 
-The repo ships a bimanual demo in ``examples/retargeting``:
+The repo ships a bimanual demo in ``examples/retargeting``. Install it from the
+repository root, in a venv set up as in :ref:`step 4 of Build from source <build-from-source-install-package>`,
+with ``grounding`` added to the extras that step installs:
 
 .. code-block:: console
 

diff --git a/docs/source/references/retargeting/wuji.rst b/docs/source/references/retargeting/wuji.rst
@@ -65,7 +65,9 @@ Run the example
 ---------------
 
 The example supports a device-free synthetic pose, recorded keypoints, and a
-real Wuji hand:
+real Wuji hand. Install it from the repository root, in a venv set up as in
+:ref:`step 4 of Build from source <build-from-source-install-package>`, with
+``wuji`` added to the extras that step installs:
 
 .. code-block:: console
 

diff --git a/examples/README.md b/examples/README.md
@@ -10,12 +10,27 @@ your own project — the last of those is the reason for the layout below.
 
 ## Running an example
 
+Build Isaac Capture from source, then set up a venv from the repository root
+exactly as in [step 4 of Build from source][install-step]: create it on the
+build's Python, activate it, and install `isaaccapture` pinned to `X.Y+local`
+with `--reinstall-package isaaccapture`. Rerun that install after every
+rebuild to replace the installed wheel. `uv pip install` finds a repo-root
+`.venv` even when it is inactive and `python` does not, so activate it in every
+terminal you run an example from.
+
 ```bash
 uv pip install -e ./examples/<name>
 python -m isaaccapture_examples.<name>
 ```
 
-Every example runs this way, and its `README.md` gives the exact command.
+Every example runs this way except camera_viz and vehicle_teleop, whose
+wrapper scripts call `.venv/bin/python` inside the example directory; their
+READMEs set up that venv. An example whose `pyproject.toml` points
+`[tool.uv.sources]` at this checkout installs an editable build instead of the
+wheel; [step 4][editable-examples] says how to rebuild it.
+
+[install-step]: https://nvidia.github.io/IsaacCapture/main/development/build_from_source/index.html#install-the-isaaccapture-pip-package
+[editable-examples]: https://nvidia.github.io/IsaacCapture/main/development/build_from_source/index.html#build-from-source-editable-examples
 
 An example with one obvious entry point puts it in `__main__.py`, so
 `python -m isaaccapture_examples.<name>` runs it. An example that is several

diff --git a/examples/camera_viz/scripts/_install_deps.sh b/examples/camera_viz/scripts/_install_deps.sh
@@ -553,6 +553,9 @@ $WITH_RTP  && PKGS+=("pybind11>=2.11" "PyGObject>=3.42,<3.52")
 # Local wheels keep version ``1.3+local`` across rebuilds; uv's --upgrade
 # no-ops on them. mtime probe forces a reinstall when the wheel's newer.
 EXTRA_UV=()
+# The wheel depends on the isaacteleop transition wheel built beside it, which
+# no index serves.
+[[ "$MODE" == full && -n "$WHEEL" ]] && EXTRA_UV+=(--find-links "$(dirname "$WHEEL")")
 if [[ "$MODE" == full && -f "$WHEEL" ]]; then
     wheel_mtime=$(stat -c %Y "$WHEEL" 2>/dev/null || echo 0)
     # Empty on a fresh venv; `|| true` keeps the no-match from aborting under pipefail+set -e.

diff --git a/examples/cloudxr_mujoco_teleop/README.md b/examples/cloudxr_mujoco_teleop/README.md
@@ -24,9 +24,8 @@ Assumes IsaacTeleop is already built and installed in this tree.
    ```bash
    curl -LsSf https://astral.sh/uv/install.sh | sh
    ```
-   With `isaaccapture` built from this tree already installed in the active
-   environment (for example
-   `uv pip install "isaaccapture[cloudxr]" --find-links=./install/wheels/`),
+   With the venv set up and `isaaccapture` installed as in
+   [Running an example](../README.md#running-an-example),
    install the example once; this pulls its Python dependencies
    (`mujoco`, `numpy`, `scipy` — see `pyproject.toml`):
    ```bash

diff --git a/examples/deviceio_live_view/README.md b/examples/deviceio_live_view/README.md
@@ -9,6 +9,7 @@ Draws live DeviceIO human tracking — hands, head, controllers, full body — i
 browser with [viser](https://viser.studio). Trackers that are inactive or absent
 are hidden rather than drawn in an error color. `CloudXRLauncher` starts the
 CloudXR runtime and WSS proxy itself, so there is nothing to launch separately.
+In a venv set up as in [Running an example](../README.md#running-an-example):
 
 ```bash
 uv pip install -e ./examples/deviceio_live_view

diff --git a/examples/haptic_feedback/README.md b/examples/haptic_feedback/README.md
@@ -14,9 +14,8 @@ flushes to an `IHapticDevice` adapter each frame.
 | `controller_haptic_example` | Pull a controller trigger to rumble that same controller — the minimal in-process `HapticSink` → `ControllerHapticDevice` wiring. |
 | `hand_pinch_haptic_example` | Pinch a fingertip toward the thumb to vibrate a haptic glove — the cross-process path (`HapticSink` → `PushTensorHapticDevice`, pushing a `HapticCommand` to a glove plugin such as Manus). |
 
-Install `isaaccapture` built from this tree into the active environment
-first, for example
-`uv pip install "isaaccapture[cloudxr]" --find-links=./install/wheels/`.
+Set up the venv and install `isaaccapture` as in
+[Running an example](../README.md#running-an-example), then:
 
 ```bash
 uv pip install -e ./examples/haptic_feedback

diff --git a/examples/mcap_record_replay/README.md b/examples/mcap_record_replay/README.md
@@ -6,7 +6,8 @@ SPDX-License-Identifier: Apache-2.0
 # MCAP record / replay
 
 Record DeviceIO tracking to an MCAP file and replay it into a viser 3D view.
-Live viewers are included for watching without recording.
+Live viewers are included for watching without recording. In a venv set up
+as in [Running an example](../README.md#running-an-example):
 
 ```bash
 uv pip install -e ./examples/mcap_record_replay
@@ -19,10 +20,6 @@ command; a replay given no path picks the newest matching recording there
 (e.g. `replay_hand` picks the newest `hands_*.mcap`) and exits if none
 match -- no silent fallback to a wrong-type recording.
 
-`uv run` (instead of an activated venv) needs an explicit `--python 3.11` --
-without it, `uv` may resolve against the system Python and fail to match the
-lockfile.
-
 The live and replay viewers bind every interface, so a browser on another
 machine can reach them at `http://<this-host>:8080`. Pass `--host 127.0.0.1` to
 keep a viewer local. Replay repeats until Ctrl+C; no loop flag is needed.

diff --git a/examples/noitom/README.md b/examples/noitom/README.md
@@ -28,11 +28,17 @@ optional plugin when you need Noitom support:
 cmake -B build -DBUILD_PLUGIN_NOITOM_MOCAP=ON -DISAAC_TELEOP_PYTHON_VERSION=3.12
 cmake --build build --target python_package python_wheel noitom_mocap_plugin --parallel
 cmake --install build
-uv pip install --find-links=install/wheels "isaaccapture[cloudxr]"
+uv venv --python 3.12 --seed .venv   # skip if .venv already runs 3.12; --clear switches it (deletes its packages)
+source .venv/bin/activate
+uv pip install "isaaccapture[cloudxr]==X.Y+local" --find-links=./install/wheels/ --reinstall-package isaaccapture
 ```
 
 Python 3.12 matches Isaac Lab 3.0, which Example 2 needs. The wheel installs
 only on the Python it was built for, so use a 3.12 venv for Example 1 too.
+`X.Y` is your build's version, the first two numbers of the repository's
+`VERSION` file. The venv and install lines follow
+[Running an example](../README.md#running-an-example); activate the venv in
+every terminal you run Example 1 from.
 
 Run `cmake --install build` again whenever `plugin.yaml` changes so the updated
 configuration is copied to `install/plugins/noitom_mocap/plugin.yaml`.
@@ -81,8 +87,7 @@ The callback runs inside Isaac Lab's own interpreter, so install isaaccapture
 and this example into *that* environment rather than a venv of your own. Build
 with `-DISAAC_TELEOP_PYTHON_VERSION=3.12` as above: Isaac Lab 3.0 runs Python
 3.12, and pip skips a wheel built for another version. Deactivate any venv
-first, because `isaaclab.sh -p` uses `$VIRTUAL_ENV` when it is set. `X.Y` is
-your build's version, the first two numbers of the repository's `VERSION` file.
+first, because `isaaclab.sh -p` uses `$VIRTUAL_ENV` when it is set.
 
 ```bash
 deactivate    # only if a venv is active
@@ -97,6 +102,8 @@ compatibility shim from your build, which maps `isaacteleop` to
 `isaaccapture`. Isaac Lab pins `isaacteleop~=1.4.145`, so pip may warn about
 that conflict.
 
+Then launch the task:
+
 ```bash
 cd <isaaclab>
 ./isaaclab.sh -p scripts/environments/teleoperation/teleop_se3_agent.py \
@@ -106,6 +113,16 @@ cd <isaaclab>
   --external_callback isaaccapture_examples.noitom.noitom_tasks.register_tasks
 ```
 
+pip treats an installed `X.Y+local` as already satisfied, so after a rebuild
+replace it explicitly. `--no-deps` keeps pip from reinstalling Isaac Lab's
+other packages:
+
+```bash
+cd <isaaclab>
+./isaaclab.sh -p -m pip install "isaaccapture==X.Y+local" \
+  --find-links <repo>/install/wheels --force-reinstall --no-deps
+```
+
 For advanced manual plugin control, start the plugin yourself and disable
 auto-launch in the Isaac Lab terminal:
 

diff --git a/examples/oglo_tactile/README.md b/examples/oglo_tactile/README.md
@@ -43,10 +43,17 @@ session, records, and draws the overlay). `oglo_heatmap.py` is the renderer.
    cmake -B build -DBUILD_PLUGIN_OGLO=ON -DBUILD_VIZ=ON
    cmake --build build --parallel
    cmake --install build           # builds the isaaccapture python wheel/package
-   uv pip install --find-links=install/wheels "isaaccapture[cloudxr]"
+   uv venv --python 3.11 --seed .venv   # skip if .venv already runs 3.11; --clear switches it (deletes its packages)
+   source .venv/bin/activate
+   uv pip install "isaaccapture[cloudxr]==X.Y+local" --find-links=./install/wheels/ --reinstall-package isaaccapture
    uv pip install -e ./examples/oglo_tactile
    ctest --test-dir build -R oglo_packet_parser --output-on-failure   # parser sanity
    ```
+   The venv and install lines follow
+   [Running an example](../README.md#running-an-example): `3.11` is the default
+   `ISAAC_TELEOP_PYTHON_VERSION` and `X.Y` the first two numbers of the
+   repository's `VERSION` file.
+
    The BLE backend (BlueZ via libdbus, permissive) connects out of the box.
    CuPy for the in-headset overlay comes with `isaaccapture[cloudxr]`.
 
@@ -67,6 +74,7 @@ session, records, and draws the overlay). `oglo_heatmap.py` is the renderer.
 **Start the CloudXR runtime** — a background service, so this shell stays free
 ```bash
 cd <repo>
+source .venv/bin/activate
 source scripts/setup_cloudxr_env.sh
 python -m isaaccapture.cloudxr.service start --accept-eula   # flag needed on first run only
 # Note the printed web-client URL, e.g.  https://<laptop-ip>:48322/
@@ -82,6 +90,7 @@ python -m isaaccapture.cloudxr.service start --accept-eula   # flag needed on fi
 **Gloves + recording + overlay**
 ```bash
 cd <repo>
+source .venv/bin/activate
 source scripts/setup_cloudxr_env.sh
 source ~/.cloudxr/run/cloudxr.env          # path printed by step above
 python -m isaaccapture_examples.oglo_tactile.oglo_teleop_record

diff --git a/examples/oxr/README.md b/examples/oxr/README.md
@@ -119,7 +119,7 @@ cmake --install build
 
 # Run Python example. Replace 3.11 with your ISAAC_TELEOP_PYTHON_VERSION and
 # X.Y with the first two numbers of VERSION.
-uv venv --python 3.11 --seed .venv
+uv venv --python 3.11 --seed .venv   # skip if .venv already runs 3.11; --clear switches it (deletes its packages)
 source .venv/bin/activate
 uv pip install "isaaccapture[cloudxr]==X.Y+local" --find-links=./install/wheels/ --reinstall-package isaaccapture
 uv pip install -e ./examples/oxr