Note

You're reading the documentation for a development version. For the latest released version, please have a look at Lyrical.

Setting up your environment - how-to

ROS relies on shell environment setup files to make commands, packages, and workspaces available. In this article, you will learn how to source setup files, make sourcing persistent, and check key environment variables. After you follow these steps, you will be ready to use ROS in new shell sessions.

Area: installation | Content type: how-to | Level: beginner, intermediate

After you install ROS, you need to configure your shell to access the relevant commands and packages. This article describes how to access ROS commands and packages by sourcing setup files and configuring environment variables.

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

Summary

You always need to source the setup files to configure your shell environment.

You can do this in one of the two ways:

  • Source the setup files in every new shell you open.

  • Add the source command to your startup script.

Without sourcing the setup files, you won’t be able to access ROS commands or find and use ROS packages.

Prerequisites

Install ROS by following the instructions on the ROS Installation page.

This guide assumes you have installed binary packages for your operating system (deb packages on Linux). If you built ROS from source, you can still follow this guide, but the path to your setup files is probably different.

Note

If you installed from source, you cannot use sudo apt install ros-<distro>-<package>.

If you use Linux or macOS, but are not already familiar with the shell, follow this tutorial.

Steps

1 Source the setup files

Use the source command to import the environment variables which enable your shell to access the ROS commands. You need to run this on every new shell you open:

$ source /opt/ros/rolling/setup.bash

If you’re not using bash, replace .bash with one of the possible values: setup.bash, setup.sh, or setup.zsh.

Note

The exact command depends on where you installed ROS. If you have problems, make sure that the file path leads to your installation.

2 (Optional) Add sourcing to your shell startup script

If you don’t want to source the setup file every time you open a new shell, you can add the following command to your shell startup script:

$ echo "source /opt/ros/rolling/setup.bash" >> ~/.bashrc

To undo this, locate your system’s shell startup script and remove the source command.

3 Check environment variables

After you source the setup files, check that your shell picked up the ROS environment variables. This confirms which distribution is active and whether the source command succeeded.

To list ROS-related environment variables, run:

$ printenv | grep -i ROS

Confirm that variables such as ROS_DISTRO and ROS_VERSION are set.

ROS_VERSION=2
ROS_PYTHON_VERSION=3
ROS_DISTRO=rolling

Note

If you later can’t find or use packages, check these variables again and make sure that they match the version and distribution you intended to use.

If the environment variables are not set correctly, return to the ROS package installation section of the installation guide you followed. If you need more specific help (because environment setup files can come from different places), get answers from the community.

3.1 (Optional) Set the ROS_DOMAIN_ID variable

ROS_DOMAIN_ID places your nodes in a DDS domain. Nodes only communicate with other nodes in the same domain, so a unique value prevents your nodes from seeing or being seen by other ROS nodes on the same network. For more details, see the domain ID article.

For the value of ROS_DOMAIN_ID, choose any integer between 0 and 101 that no other ROS user on your network is using. If you are working alone or on an isolated network, any value in that range is fine.

To set the ROS_DOMAIN_ID variable, run:

$ export ROS_DOMAIN_ID=<your_domain_id>

To maintain this setting between shell sessions, you can add the command to your shell startup script:

$ echo "export ROS_DOMAIN_ID=<your_domain_id>" >> ~/.bashrc

3.2 (Optional) Set the ROS_AUTOMATIC_DISCOVERY_RANGE variable

By default, ROS nodes try to discover other nodes across the local network, not only on your machine. The ROS_AUTOMATIC_DISCOVERY_RANGE environment variable lets you limit how far that discovery reaches. This is helpful in settings such as classrooms, where multiple robots may publish to the same topic and interfere with one another.

To limit discovery to the local machine, set the variable to LOCALHOST:

$ export ROS_AUTOMATIC_DISCOVERY_RANGE=LOCALHOST

To maintain this setting between shell sessions, you can add the command to your shell startup script:

$ echo "export ROS_AUTOMATIC_DISCOVERY_RANGE=LOCALHOST" >> ~/.bashrc

For other values and more advanced discovery options, see Improved Dynamic Discovery.

4 Verify your environment configuration

Confirm that your shell has the ROS paths and variables from the earlier steps in this article, including any optional variables you set.

Open a terminal session:

  • If you only source manually, open a new terminal window and run your source, ., or call command.

  • If you use a startup script, open a new terminal window.

In your terminal window, run:

$ ros2 --help

If usage text appears, your shell picked up the ROS command paths from the setup files in this guide.

If you set optional ROS_DOMAIN_ID or ROS_AUTOMATIC_DISCOVERY_RANGE values earlier in this guide, run the environment check again in this terminal session to confirm you see the values you expect:

$ printenv | grep -i ROS

Related content

More articles:

FAQs

Do I need to source the setup files in every new terminal?

Yes. ROS commands and packages are only available in shells where you have sourced the setup files. To avoid doing this manually each time, add the source command to your shell startup script.

How do I check that my ROS environment is configured correctly?

List ROS-related environment variables (for example with printenv | grep -i ROS on Linux or macOS, or set | findstr -i ROS on Windows). Confirm that ROS_DISTRO and ROS_VERSION are set, then run ros2 --help. If usage text appears, your shell picked up the ROS command paths from the setup files.

Why is the ros2 command not found after I installed ROS?

Installing ROS does not configure your shell automatically. You must source the setup file for your installation (for example /opt/ros/rolling/setup.bash on Linux when using deb packages) in each new shell, or add that command to your startup script.

What is ROS_DOMAIN_ID and when should I set it?

ROS_DOMAIN_ID selects which logical DDS domain your nodes use for discovery. Nodes only discover each other when they share the same domain ID. Set a unique value when you need to isolate groups of nodes, such as in classrooms where multiple robots would otherwise see the same topics.

Can I install multiple ROS distributions on the same computer?

Yes. Install each distribution separately, then source the setup file for the one you want to use in that shell session. Combining workspaces through sourcing also lets you layer local overlays on top of the core underlay.