Skip to content

Update Installing on Ubuntu howto #6812

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
kacperbojakowski-3di wants to merge 2 commits into
base: rolling
Choose a base branch
from
+164 −81
Open

Update Installing on Ubuntu howto #6812

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
89182e5
Update Installing on Ubuntu howto
kacperbojakowski-3di Apr 13, 2026
0846f59
Merge branch 'rolling' into installing-on-ubuntu-howto
kacperbojakowski-3di May 19, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
245 changes: 164 additions & 81 deletions source/Installation/Ubuntu-Install-Debs.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,145 +3,228 @@
Installation/Linux-Install-Debians
Installation/Ubuntu-Install-Debians

Ubuntu (deb packages)
=====================
Installing on Ubuntu - how-to
=============================

.. contents:: Table of Contents
:depth: 2
ROS is supported on a range of different platforms.
In this article, you will learn how to install ROS deb packages on Ubuntu.
After you follow these steps, you'll be ready to work with ROS.

**Area: ROS-installation | Content-type: how-to | Experience: beginner, intermediate**

.. contents:: Contents
:depth: 3
:local:

Deb packages for ROS 2 {DISTRO_TITLE_FULL} are currently available for Ubuntu Resolute (26.04).
The Rolling Ridley distribution will change target platforms from time to time as new platforms are selected for development.
The target platforms are defined in `REP 2000 <https://reps.openrobotics.org/rep-2000/>`__.
Most people will want to use a stable ROS distribution.
Summary
-------

Resources
---------
Deb packages for {DISTRO_TITLE_FULL} are available for Ubuntu Noble (24.04).
We recommend using this current distribution for most situations, the support for this platform is stable.

* Status Page:
Resources for this distribution are as follows:

* ROS 2 {DISTRO_TITLE} (Ubuntu Resolute Raccoon 26.04): `amd64 <http://repo.ros2.org/status_page/ros_{DISTRO}_default.html>`__\ , `arm64 <http://repo.ros2.org/status_page/ros_{DISTRO}_unv8.html>`__
* Status page: ROS 2 {DISTRO_TITLE} (Ubuntu Noble 24.04): `amd64 <http://repo.ros2.org/status_page/ros_{DISTRO}_default.html>`__\ , `arm64 <http://repo.ros2.org/status_page/ros_{DISTRO}_unv8.html>`__
* `Jenkins Instance <http://build.ros2.org/>`__
* `Repositories <http://repo.ros2.org>`__

System setup
------------
The Rolling Ridley development distribution may be supported on different platforms, as new platforms are selected for development.
Future plans for target platforms are defined in `REP 2000 <https://reps.openrobotics.org/rep-2000/>`__.

Set locale
^^^^^^^^^^
Prerequisites
-------------

.. include:: _Ubuntu-Set-Locale.rst
Check the :doc:`installation requirements <../Installation>`.

Enable required repositories
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Steps
-----

.. include:: _Apt-Repositories.rst
1 Set up your system
^^^^^^^^^^^^^^^^^^^^

.. _linux-install-debs-install-ros-2-packages:
#. Set your locale.

Install development tools (optional)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Make sure you have a locale which supports ``UTF-8``.
If you are in a minimal environment (such as a docker container), the locale may be something minimal like ``POSIX``.
We test with the following settings.
However, it should be fine if you're using a different UTF-8 supported locale.

If you are going to build ROS packages or otherwise do development, you can also install the development tools:
.. code-block:: console

.. code-block:: console
$ locale # check for UTF-8
$ sudo apt update && sudo apt install locales
$ sudo locale-gen en_US en_US.UTF-8
$ sudo update-locale LC_ALL=en_US.UTF-8 LANG=en_US.UTF-8
$ export LANG=en_US.UTF-8
$ locale # verify settings

$ sudo apt update && sudo apt install ros-dev-tools
#. Enable the required repositories.

Install ROS 2
-------------
You will need to add the ROS 2 apt repository to your system.

a. Ensure that the `Ubuntu Universe repository <https://help.ubuntu.com/community/Repositories/Ubuntu>`_ is enabled.

.. code-block:: console

$ sudo apt install software-properties-common
$ sudo add-apt-repository universe

b. Install the `ros-apt-source <https://github.com/ros-infrastructure/ros-apt-source/>`_ packages.

These provide keys and apt source configuration for the various ROS repositories.

.. code-block:: console

$ sudo apt update && sudo apt install curl -y
$ export ROS_APT_SOURCE_VERSION=$(curl -s https://api.github.com/repos/ros-infrastructure/ros-apt-source/releases/latest | grep -F "tag_name" | awk -F'"' '{print $4}')
$ curl -L -o /tmp/ros2-apt-source.deb "https://github.com/ros-infrastructure/ros-apt-source/releases/download/${ROS_APT_SOURCE_VERSION}/ros2-apt-source_${ROS_APT_SOURCE_VERSION}.$(. /etc/os-release && echo ${UBUNTU_CODENAME:-${VERSION_CODENAME}})_all.deb"
$ sudo dpkg -i /tmp/ros2-apt-source.deb

Installing the ros2-apt-source package configures ROS repositories for your system.
Updates to repository configuration occur automatically when new versions of this package are released to the ROS repositories.

#. Optional: Install development tools.

For building packages or other ROS development work, install ``ros-dev-tools``:

.. code-block:: console

$ sudo apt update && sudo apt install ros-dev-tools

Update your apt repository caches after setting up the repositories.
2 Install ROS
^^^^^^^^^^^^^

.. code-block:: console
1. Update your apt repository caches.

$ sudo apt update
.. code-block:: console

.. include:: _Apt-Upgrade-Admonition.rst
$ sudo apt update

Desktop Install (Recommended): ROS, RViz, demos, tutorials.
2. Ensure your system is up to date.

.. code-block:: console
ROS packages are built on frequently updated Ubuntu systems.
Always make sure that your system is up to date before installing new packages.

$ sudo apt install ros-{DISTRO}-desktop
.. code-block:: console

ROS-Base Install (Bare Bones): Communication libraries, message packages, command line tools.
No GUI tools.
$ sudo apt upgrade

.. code-block:: console
3. Install ROS using one of the following methods:

$ sudo apt install ros-{DISTRO}-ros-base
.. _linux-install-debs-install-ros-2-packages:

Install additional RMW implementations (optional)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Desktop install (Recommended): ROS, RViz, demos, tutorials.

The default middleware that ROS 2 uses is ``Fast DDS``, but the middleware (RMW) can be replaced at runtime.
See the :doc:`guide <../How-To-Guides/Working-with-multiple-RMW-implementations>` on how to work with multiple RMWs.
.. code-block:: console

Setup environment
-----------------
$ sudo apt install ros-{DISTRO}-desktop

Set up your environment by sourcing the following file.
ROS-Base install (Bare Bones): Communication libraries, message packages, command line tools.
No GUI tools.

.. code-block:: console
.. code-block:: console

$ source /opt/ros/{DISTRO}/setup.bash
$ sudo apt install ros-{DISTRO}-ros-base

.. note::
4. Optional: Install additional RMW implementations.

Replace ``.bash`` with your shell if you're not using bash.
Possible values are: ``setup.bash``, ``setup.sh``, ``setup.zsh``.
You can install optional RMW packages when your project needs a supported DDS or Zenoh vendor other than the default.
The default middleware that ROS 2 uses is ``Fast DDS``, but the middleware (RMW) can be replaced at runtime.
See the :doc:`guide <../How-To-Guides/Working-with-multiple-RMW-implementations>` on how to work with multiple RMWs.

Try some examples
-----------------
3 Set up your environment
^^^^^^^^^^^^^^^^^^^^^^^^^

If you installed ``ros-{DISTRO}-desktop`` above you can try some examples.
#. Set up your environment by sourcing the following file.

In one terminal, source the setup file and then run a C++ ``talker``\ :
.. code-block:: console

.. code-block:: console
$ source /opt/ros/{DISTRO}/setup.bash

$ source /opt/ros/{DISTRO}/setup.bash
$ ros2 run demo_nodes_cpp talker
.. note::

In another terminal source the setup file and then run a Python ``listener``\ :
If you are not using bash, replace ``.bash`` with your shell.
Possible values are: ``setup.bash``, ``setup.sh``, ``setup.zsh``.

.. code-block:: console
4 Test the installation
^^^^^^^^^^^^^^^^^^^^^^^

$ source /opt/ros/{DISTRO}/setup.bash
$ ros2 run demo_nodes_py listener
If you installed ``ros-{DISTRO}-desktop``, you can try some examples to check if the installation has been successful.

You should see the ``talker`` saying that it's ``Publishing`` messages and the ``listener`` saying ``I heard`` those messages.
This verifies both the C++ and Python APIs are working properly.
Hooray!
#. In one terminal, source the setup file, then run a C++ talker:

.. code-block:: console

$ source /opt/ros/{DISTRO}/setup.bash
$ ros2 run demo_nodes_cpp talker

#. In another terminal, source the setup file, then run a Python listener:

.. code-block:: console

$ source /opt/ros/{DISTRO}/setup.bash
$ ros2 run demo_nodes_py listener

You should see the talker saying that it's publishing messages and the listener saying that it hears those messages.
This verifies both the C++ and Python APIs are working properly.

If you have issues with the installation, check the :doc:`troubleshooting techniques <../How-To-Guides/Installation-Troubleshooting>`.

If you want to use other RMW implementations, you can check the :doc:`guide <./RMW-Implementations>`.

Next steps
----------

Continue with the :doc:`tutorials and demos <../../Tutorials>` to configure your environment, create your own workspace and packages, and learn ROS 2 core concepts.
After the installation is complete, you can proceed with :doc:`configuring your environment <../Tutorials/Beginner-CLI-Tools/Configuring-ROS2-Environment>`.

We recommend that you get familiar with key ROS concepts and check out the tutorials:

* :doc:`First steps with ROS - learning path <../First-Steps>`

Related content
---------------

More articles:

* :doc:`Create a workspace <../Tutorials/Beginner-Client-Libraries/Creating-A-Workspace/Creating-A-Workspace>`
* :doc:`About ROS <../About-ROS>`

Packages/reference:

* `ros-{DISTRO}-desktop <https://index.ros.org/p/desktop/#{DISTRO}>`__: A package which extends ``ros_base`` and includes high level packages like visualization tools and demos.
* `ros-{DISTRO}-ros-base <https://index.ros.org/p/ros_base/#{DISTRO}>`__: A package which extends ``ros_core`` and includes other basic functionalities like tf2 and urdf.
* `demo_nodes_cpp <https://index.ros.org/p/demo_nodes_cpp/#{DISTRO}>`__: C++ nodes which were previously in the ros2/examples repository but are now just used for demo purposes.
* `demo_nodes_py <https://index.ros.org/p/demo_nodes_py/#{DISTRO}>`__: Python nodes which were previously in the ros2/examples repository but are now just used for demo purposes.
* `ros2-apt-source <https://github.com/ros-infrastructure/ros-apt-source/>`__: Source and key configuration for the ROS 2 apt repository.
* `ros-dev-tools <https://github.com/ros-infrastructure/infra-variants/tree/latest/ros-dev-tools>`__: Variant which includes packages generally useful during ROS development.

FAQs
----

Which Ubuntu platforms are supported?
ROS 2 {DISTRO_TITLE_FULL} is available for Ubuntu Noble (24.04).

Troubleshoot
------------
Why am I seeing <some error or symptom of installation issue>?
See :doc:`../How-To-Guides/Installation-Troubleshooting`.

Troubleshooting techniques can be found :doc:`here <../How-To-Guides/Installation-Troubleshooting>`.
Can I switch from binaries to a source-based install?
Yes.
See :doc:`Alternatives/Ubuntu-Development-Setup`.

Uninstall
---------
.. _ubuntu-debs-uninstall:

If you need to uninstall ROS 2 or switch to a source-based install once you
have already installed from binaries, run the following command:
How do I uninstall ROS?
If you need to uninstall ROS 2 or switch to a source-based install once you have already installed from binaries, run the following command:

.. code-block:: console
.. code-block:: console

$ sudo apt remove '~nros-{DISTRO}-*' && sudo apt autoremove
$ sudo apt remove '~nros-{DISTRO}-*' && sudo apt autoremove

You may also want to remove the repository:
You may also want to remove the repository:

.. code-block:: console
.. code-block:: console

$ sudo apt remove ros2-apt-source
$ sudo apt update
$ sudo apt autoremove
$ sudo apt upgrade # Consider upgrading for packages previously shadowed.
$ sudo apt remove ros2-apt-source
$ sudo apt update
$ sudo apt autoremove
$ sudo apt upgrade # Consider upgrading for packages previously shadowed.
Loading