ros2: command not found: source the ROS 2 setup file

A new terminal does not know about ROS 2 until you source its setup file. Run source /opt/ros/<distro>/setup.bash first.

What the message means

The ros2 tool and its libraries are added to your path by the setup script. Each terminal needs it, unless you put the line in your start-up file.

Fix it in this order

1. Run source /opt/ros/<distro>/setup.bash with your own distribution name, such as humble or jazzy.
2. Add the same line to the end of ~/.bashrc so new terminals do it for you.
3. Check that ROS 2 is installed by listing /opt/ros.
4. After building your own workspace also source install/setup.bash from the workspace folder.
5. Open a new terminal after editing .bashrc, or run source ~/.bashrc.

Why it happens

ROS 2 installs its command-line tools and libraries in a folder under /opt/ros, named after the distribution. The shell only finds ros2 when that folder’s setup script has updated the PATH and library variables in the current session. Each new terminal starts with a clean environment, so the setup has to run again there. Opening a new window without the setup line is the usual reason the command disappears.

Once the setup file is in your shell start-up file, every new terminal runs it automatically. Workspaces you build yourself add a second setup file, install/setup.bash, which layers your packages on top of the base install. Sourcing order matters: the base distribution first, then your workspace. If the folder under /opt/ros is missing, ROS 2 is not installed, and no source line will help.

If you see this, do this

You see	Do this
Works in one terminal only	Add the line to .bashrc.
Distribution folder missing	ROS 2 is not installed.

Confirm the fix

1. Run echo $ROS_DISTRO after sourcing. It should print the distribution name, such as humble or jazzy, confirming the environment variables are set.
2. Open a fresh terminal without sourcing anything and run which ros2. Empty output confirms that only the setup line supplies the command.
3. Run ls /opt/ros and check that your distribution folder appears. Then run ros2 topic list, which should return without an error message.

Common mistake: Many readers assume that sourcing ROS 2 once in one terminal makes the command available everywhere, when each new shell needs the setup, usually through a line in .bashrc.

Related

Gazebo and ROS 2 tutorial, package not found after build.

Last reviewed: November 2026. These are the usual causes and the order that finds them fastest. Test on your own board; clones and cables differ.

Why this happens

The ros2 command is not on the default PATH. The ROS 2 install keeps its tools under /opt/ros/<distro>, and the setup script in that folder adds them to the shell’s environment. It sets PATH so ros2 is found, AMENT_PREFIX_PATH so packages are found, PYTHONPATH and LD_LIBRARY_PATH for libraries, and ROS_DISTRO to the distribution name.

Those are variables of the running shell, so they do not carry to other terminals or reboots. A new terminal starts clean, and the command seems to vanish. Sourcing the file once per terminal, or from ~/.bashrc, fixes it. A workspace you build yourself has its own install/setup.bash, which should be sourced after the base installation.

How to confirm the cause

• Run ls /opt/ros. A folder named for your distribution, such as humble or jazzy, means ROS 2 is installed. An error means it is not.
• Run which ros2. No output in a fresh terminal confirms the command is not on the path yet.
• After sourcing, run echo $ROS_DISTRO. It should print the distribution name.
• Run printenv | grep -i ros to see the variables the setup file set.
• Check which shell you use with echo $SHELL. A bash setup file does not suit zsh, which needs setup.zsh.

Worked example

These commands show the whole sequence for a distribution called humble. Replace it with the folder you found.

ls /opt/ros
source /opt/ros/humble/setup.bash
echo $ROS_DISTRO
ros2 topic list
echo "source /opt/ros/humble/setup.bash" >> ~/.bashrc

The last line appends the source command to your start-up file, so every new terminal sets up ROS 2 on its own. Open a new terminal and check which ros2 again to confirm.

Common mistakes

• Typing the angle brackets from a tutorial and not replacing <distro> with the real name.
• Using setup.bash in zsh, or the other way round.
• Sourcing the workspace setup before the base setup.
• Running the command from a script that starts its own shell without the setup.

If this did not fix it

• ROS 2 not installed, or only partly installed: check the install steps for your distribution.
• Conda or another Python environment changing PATH: try in a fresh terminal without it.
• Running inside WSL or a container that does not have the installation.