From f3812e41b8ab360437980263cb79f192eda09e01 Mon Sep 17 00:00:00 2001 From: Marina Nelson Date: Sun, 20 Jul 2025 14:24:43 -0400 Subject: [PATCH 1/3] Update Using-Python-Packages.rst Installing via a virtual environment --- .../How-To-Guides/Using-Python-Packages.rst | 96 +++++++++++++++++-- 1 file changed, 89 insertions(+), 7 deletions(-) diff --git a/source/How-To-Guides/Using-Python-Packages.rst b/source/How-To-Guides/Using-Python-Packages.rst index 56d2793f680..c91d30e18ce 100644 --- a/source/How-To-Guides/Using-Python-Packages.rst +++ b/source/How-To-Guides/Using-Python-Packages.rst @@ -17,13 +17,13 @@ Using Python Packages with ROS 2 .. note:: A cautionary note, if you intended to use pre-packaged binaries (either ``deb`` files, or the binary archive distributions), the Python interpreter must match what was used to build the original binaries. - If you intend to use something like ``virtualenv`` or ``pipenv``\, make sure to use the system interpreter. + If you intend to use something like ``virtualenv`` or ``pipenv``, make sure to use the system interpreter. If you use something like ``conda``, it is very likely that the interpreter will not match the system interpreter and will be incompatible with ROS 2 binaries. Installing via ``rosdep`` ------------------------- -The fastest way to include third-party python packages is to use their corresponding rosdep keys, if available. +The fastest way to include third-party Python packages is to use their corresponding rosdep keys, if available. ``rosdep`` keys can be checked via: * https://github.com/ros/rosdistro/blob/master/rosdep/base.yaml @@ -61,9 +61,13 @@ If the package is available on PyPI and you want to install locally to your user $ python3 -m pip install -U --user pyserial + Installing via a virtual environment ------------------------------------ +ROS 2 packages using the ``ament_python`` build type can be modified to install Python entry point scripts using a virtual environment interpreter. +This allows Python nodes to run with dependencies installed in a virtual environment. + First, create a Colcon workspace: .. code-block:: console @@ -71,7 +75,17 @@ First, create a Colcon workspace: $ mkdir -p ~/colcon_venv/src $ cd ~/colcon_venv/ -Then setup your virtual environment: +There are several Python packages required to run your Python node using a virtual environment. +These packages are installed in your system environment. +Export these packages and their version dependencies to a ``requirements.txt`` file: + +.. code-block:: console + + $ source /opt/ros/rolling/setup.bash # Source installation to ensure correct Python interpreter is used + $ python3 -m pip freeze | grep -E '^(PyYAML|setuptools|typing_extensions)==' > requirements.txt + + +After exporting these requirements, setup your virtual environment: .. code-block:: console @@ -79,19 +93,87 @@ Then setup your virtual environment: $ source ./venv/bin/activate $ touch ./venv/COLCON_IGNORE # Make sure that colcon does not try to build the venv -Next, install the Python packages that you want in your virtual environment: + +Next, install the required Python packages: + +.. code-block:: console + + $ python3 -m pip install -r requirements.txt + +After, install the Python packages that you want in your virtual environment: .. code-block:: console - $ python3 -m pip install gtsam pyserial… etc + $ python3 -m pip install gtsam pyserial # ... etc. -Now you can build your workspace and run your python node that depends on packages installed in your virtual environment. +Place the ROS 2 package containing your Python node into the ``src``` directory of your Colcon workspace. +Open ``setup.py`` and add the ``options`` field to the ``setup`` call: + +.. code-block:: python + + options={ + 'build_scripts': { + 'executable': '' + } + } + +Replace ```` with the path to your virtual environment Python interpreter. +If you do not know the path, you can find it by running ``which python`` in the terminal while the virtual environment is active. + +.. note:: + + All Python nodes in the modified ROS 2 package will run using the virtual environment Python interpreter. + If you need your Python nodes to run using different Python packages, you should move those nodes to separate ROS 2 packages and create separate virtual environments. + +Now you can build the ROS 2 package in your workspace and run your Python node that depends on packages installed in your virtual environment. .. code-block:: console - $ source /opt/ros/{DISTRO}/setup.bash # Source {DISTRO_TITLE} and build + $ source /opt/ros/rolling/setup.bash # Source Rolling and build $ colcon build +Installing via a virtual environment with symbolic links +-------------------------------------------------------- + +If you want to run your Python nodes using dependencies installed in a virtual environment, but you also build your ROS 2 package using the ``--symlink-install`` option to create symbolic links to those Python nodes, then the process varies slightly. + +First, create a Colcon workspace: + +.. code-block:: console + + $ mkdir -p ~/colcon_venv/src + $ cd ~/colcon_venv/ + +There are several system Python packages required to build your Python nodes with symbolic links and then run them using a virtual environment. +Export these packages and their version dependencies to a ``requirements.txt`` file: + +.. code-block:: console + + $ source /opt/ros/rolling/setup.bash # Source installation to ensure correct Python interpreter is used + $ python3 -m pip freeze | grep -E '^(colcon-common-extensions|PyYAML|setuptools|typing_extensions)==' > requirements.txt + +After exporting these requirements, setup your virtual environment: + +.. code-block:: console + + $ virtualenv -p python3 ./venv # Make a virtual env and activate it + $ source ./venv/bin/activate + $ touch ./venv/COLCON_IGNORE # Make sure that colcon does not try to build the venv + +Next, install the required Python packages: + +.. code-block:: console + + $ python3 -m pip install -r requirements.txt + +Now, with your virtual environment active, you can build the ROS 2 package with symbolic links and run your Python node that depends on packages installed in your virtual environment. +Replace ```` with the name of the package containing your Python node. + +.. code-block:: console + + $ source /opt/ros/rolling/setup.bash # Source Rolling and build + $ python3 -m colcon build --symlink-install --packages-select + .. note:: If you want to release your package using Bloom, you should add the packages you require to ``rosdep``, see the `rosdep key contribution guide`_. From 07c504408b89b190e49d29cfa51ca3ea07bef669 Mon Sep 17 00:00:00 2001 From: Marina Nelson Date: Sun, 20 Jul 2025 14:31:39 -0400 Subject: [PATCH 2/3] Update Using-Python-Packages.rst Grammatrical fixes --- source/How-To-Guides/Using-Python-Packages.rst | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/source/How-To-Guides/Using-Python-Packages.rst b/source/How-To-Guides/Using-Python-Packages.rst index c91d30e18ce..37d126faacb 100644 --- a/source/How-To-Guides/Using-Python-Packages.rst +++ b/source/How-To-Guides/Using-Python-Packages.rst @@ -66,7 +66,7 @@ Installing via a virtual environment ------------------------------------ ROS 2 packages using the ``ament_python`` build type can be modified to install Python entry point scripts using a virtual environment interpreter. -This allows Python nodes to run with dependencies installed in a virtual environment. +This allows Python nodes to run with dependencies installed in virtual environments. First, create a Colcon workspace: @@ -106,7 +106,7 @@ After, install the Python packages that you want in your virtual environment: $ python3 -m pip install gtsam pyserial # ... etc. -Place the ROS 2 package containing your Python node into the ``src``` directory of your Colcon workspace. +Place the ROS 2 package containing your Python node into the ``src`` directory of your Colcon workspace. Open ``setup.py`` and add the ``options`` field to the ``setup`` call: .. code-block:: python @@ -135,7 +135,7 @@ Now you can build the ROS 2 package in your workspace and run your Python node t Installing via a virtual environment with symbolic links -------------------------------------------------------- -If you want to run your Python nodes using dependencies installed in a virtual environment, but you also build your ROS 2 package using the ``--symlink-install`` option to create symbolic links to those Python nodes, then the process varies slightly. +If you want to run your Python nodes using dependencies installed in a virtual environment, but you also want to build your ROS 2 package using the ``--symlink-install`` option to create symbolic links to those Python nodes, then the process varies slightly. First, create a Colcon workspace: @@ -144,7 +144,7 @@ First, create a Colcon workspace: $ mkdir -p ~/colcon_venv/src $ cd ~/colcon_venv/ -There are several system Python packages required to build your Python nodes with symbolic links and then run them using a virtual environment. +There are several required Python packages installed in your system environment Python. Export these packages and their version dependencies to a ``requirements.txt`` file: .. code-block:: console @@ -166,7 +166,13 @@ Next, install the required Python packages: $ python3 -m pip install -r requirements.txt -Now, with your virtual environment active, you can build the ROS 2 package with symbolic links and run your Python node that depends on packages installed in your virtual environment. +After, install the Python packages that you want in your virtual environment: + +.. code-block:: console + + $ python3 -m pip install gtsam pyserial # ... etc. + +Now, while your virtual environment is active, you can build your ROS 2 package and run your Python node that depends on packages installed in your virtual environment. Replace ```` with the name of the package containing your Python node. .. code-block:: console From 7969bbe611bdecfb75578bf59c49495b82d07dc2 Mon Sep 17 00:00:00 2001 From: Marina Nelson Date: Sun, 20 Jul 2025 17:20:52 -0400 Subject: [PATCH 3/3] Update Using-Python-Packages.rst replace rolling with distro --- source/How-To-Guides/Using-Python-Packages.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/source/How-To-Guides/Using-Python-Packages.rst b/source/How-To-Guides/Using-Python-Packages.rst index 37d126faacb..32a9b75fd03 100644 --- a/source/How-To-Guides/Using-Python-Packages.rst +++ b/source/How-To-Guides/Using-Python-Packages.rst @@ -81,7 +81,7 @@ Export these packages and their version dependencies to a ``requirements.txt`` f .. code-block:: console - $ source /opt/ros/rolling/setup.bash # Source installation to ensure correct Python interpreter is used + $ source /opt/ros/{DISTRO}/setup.bash # Source installation to ensure correct Python interpreter is used $ python3 -m pip freeze | grep -E '^(PyYAML|setuptools|typing_extensions)==' > requirements.txt @@ -129,7 +129,7 @@ Now you can build the ROS 2 package in your workspace and run your Python node t .. code-block:: console - $ source /opt/ros/rolling/setup.bash # Source Rolling and build + $ source /opt/ros/{DISTRO}/setup.bash # Source {DISTRO_TITLE} and build $ colcon build Installing via a virtual environment with symbolic links @@ -149,7 +149,7 @@ Export these packages and their version dependencies to a ``requirements.txt`` f .. code-block:: console - $ source /opt/ros/rolling/setup.bash # Source installation to ensure correct Python interpreter is used + $ source /opt/ros/{DISTRO}/setup.bash # Source installation to ensure correct Python interpreter is used $ python3 -m pip freeze | grep -E '^(colcon-common-extensions|PyYAML|setuptools|typing_extensions)==' > requirements.txt After exporting these requirements, setup your virtual environment: @@ -177,7 +177,7 @@ Replace ```` with the name of the package containing your Python n .. code-block:: console - $ source /opt/ros/rolling/setup.bash # Source Rolling and build + $ source /opt/ros/{DISTRO}/setup.bash # Source {DISTRO_TITLE} and build $ python3 -m colcon build --symlink-install --packages-select .. note::