docs(install): create a uv venv before installing isaaccapture

docs/source/development/build_from_source/index.rst

@@ -334,8 +334,16 @@ The CI uses ``ctest`` (see :code-file:`build-ubuntu.yml <.github/workflows/build
 
 The build writes two wheels to ``./install/wheels/``: ``isaaccapture`` and the ``isaacteleop``
 transition wheel it depends on. The ``isaaccapture`` wheel only installs on the Python version it
-was built for (``ISAAC_TELEOP_PYTHON_VERSION``, 3.11 by default), so create and activate a venv
-with that version first.
+was built for (``ISAAC_TELEOP_PYTHON_VERSION``, 3.11 by default), so install it into a virtual
+environment with that version. Without one, ``pip install`` fails on Ubuntu 24.04 with
+``externally-managed-environment`` and ``uv pip install`` with ``No virtual environment found``.
+From the repository root:
+
+.. code-block:: bash
+
+   # Replace 3.11 with your ISAAC_TELEOP_PYTHON_VERSION. --seed adds pip for the pip command below.
+   uv venv --python 3.11 --seed .venv
+   source .venv/bin/activate
 
 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

docs/source/references/build.rst

@@ -57,8 +57,10 @@ The project uses a modern CMake target-based approach. Libraries export namespac
 Using the Python wheel
 ----------------------
 
-After building, install the wheels with ``uv`` or ``pip``, pinning the local build's version
-``X.Y+local`` (``X.Y`` from the repository's ``VERSION`` file):
+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
+``pip``, pinning the local build's version ``X.Y+local`` (``X.Y`` from the repository's ``VERSION``
+file):
 
 .. code-block:: bash
 
@@ -80,7 +82,8 @@ In addition to the classic CMake flow above (which stages the package
 and produces a wheel under ``install/wheels/``), the repository ships a root
 :code-file:`pyproject.toml` that exposes ``isaaccapture`` through the
 `scikit-build-core <https://scikit-build-core.readthedocs.io/>`_ build backend,
-driving the *same* top-level ``CMakeLists.txt`` (so the two paths coexist):
+driving the *same* top-level ``CMakeLists.txt`` (so the two paths coexist). Run it inside an
+activated virtual environment as well:
 
 .. code-block:: bash
 

docs/source/teleop/quick_start.rst

@@ -40,15 +40,31 @@ to clone the repository for a couple quick samples to run.
    replaces the legacy package and keeps old imports working temporarily.
    See :doc:`/development/migration`.
 
-In a new terminal, activate your preferred virtual or conda environment, then install the latest
-stable release from PyPI:
+Install the package into a virtual environment. Without one, ``pip install`` fails on Ubuntu 24.04
+with ``externally-managed-environment`` and ``uv pip install`` with ``No virtual environment
+found``. In a new terminal, from the repository root, create and activate one with
+`uv <https://docs.astral.sh/uv/>`__, which downloads the requested Python if the system lacks it
+(Python 3.11 to 3.13 are supported). If ``uv`` is missing, install it first as shown in
+:ref:`one-time-setup`.
 
 .. code-block:: bash
 
-   pip install 'isaaccapture[cloudxr,retargeters]~=1.0'
+   # --seed adds pip, so plain pip install also works in this venv.
+   uv venv --python 3.11 --seed .venv
+   source .venv/bin/activate
+
+To use an existing venv, or a conda environment other than ``base`` (``uv`` treats ``base`` as a
+system Python), activate it and skip ``uv venv``. Activate the environment again in every new
+terminal you use for the steps below.
+
+Install the latest stable release from PyPI:
+
+.. code-block:: bash
+
+   uv pip install 'isaaccapture[cloudxr,retargeters]~=1.0'
 
 Pre-release builds are published between stable releases. Picking one up takes the NVIDIA index
-and an opt-in to pre-release versions — shown here with `uv <https://docs.astral.sh/uv/>`__:
+and an opt-in to pre-release versions:
 
 .. code-block:: bash