diff --git a/source/How-To-Guides/Using-Python-Packages.rst b/source/How-To-Guides/Using-Python-Packages.rst index 56d2793f68..32a9b75fd0 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 virtual environments. + 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/{DISTRO}/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,93 @@ 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. + +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: -Now you can build your workspace and run your python node that depends on packages installed in your virtual environment. +.. 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 $ 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 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: + +.. code-block:: console + + $ mkdir -p ~/colcon_venv/src + $ cd ~/colcon_venv/ + +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 + + $ 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: + +.. 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 + +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 + + $ source /opt/ros/{DISTRO}/setup.bash # Source {DISTRO_TITLE} 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`_.