ROS 2 "package not found" after colcon build

A built workspace is not visible until you source its install/setup.bash file in that terminal.

What the message means

colcon puts the built packages in the install folder. The setup script tells the shell where they are.

Fix it in this order

Run source install/setup.bash from the root of your workspace after each build.
Source the main ROS 2 setup file first, then the workspace.
Check that the build finished without errors, and that the package name matches package.xml.
For Python packages check that the entry point is in setup.py.
Open a new terminal and source again if you changed the environment.

Why it happens

colcon builds your packages into the install folder, but the shell does not search that folder by default. The setup script adds the built packages to the paths ROS 2 uses, and it only affects the terminal where you run it.

That is why a new terminal, or a build that you did not source afterwards, cannot find the package. Source the main ROS 2 setup first and your workspace second, and check that the build finished without errors.

If you see this, do this

You see	Do this
Works in the build terminal only	Source in each terminal.
Still missing	Check the package name and the build output.

ros2 command not found, topic list empty.

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

ROS 2 finds packages through environment variables, mainly AMENT_PREFIX_PATH. Building with colcon creates an install folder, but a shell only learns about it when you source the setup file inside it. The change belongs to that one terminal; a new terminal starts without it.

Overlay order matters too. The main ROS 2 setup is the underlay, and your workspace goes on top. The install/setup.bash file also sources the underlays it was built against, while local_setup.bash adds only that workspace.

How to confirm the cause

Run echo $AMENT_PREFIX_PATH. Your workspace’s install folder should appear in the list.
Run ros2 pkg prefix your_package. A path in your install folder means the package is found.
List the install folder. A folder named after your package should exist; if not, the build did not produce it.
Read the end of the colcon output for a line that says the package finished, and for any failed packages.
Open package.xml and compare the name tag with the name you typed. They must match exactly.

Worked example

A clean build and source sequence. Replace humble with your own distribution name and my_pkg with your package.

cd ~/ros2_ws
source /opt/ros/humble/setup.bash
colcon build --packages-select my_pkg
source install/setup.bash
ros2 pkg prefix my_pkg
ros2 pkg list | grep my_pkg

Common mistakes

Sourcing install/setup.bash from inside src or from the wrong folder.
Sourcing before the first build has created the install folder.
Building in a terminal that already has an older workspace sourced, which mixes overlays.
Mixing up the folder name and the package name.
Using a bash setup file in a zsh shell.

If this did not fix it

The package is found but the executable is not. That is a different message; check the entry points in setup.py or the install rules in CMakeLists.txt.
Missing dependencies in package.xml, which make the build fail.
Stale build output. Remove the build, install and log folders in your workspace and build again.

ROS 2 “package not found” after colcon build: source install/setup.bash