> For the complete documentation index, see [llms.txt](https://docs.hello-robot.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hello-robot.com/stretch4_install/docs/ros_workspace.md). # Updating your ROS Workspace ## Why ROS1 and ROS2 organize software by "workspaces", where ROS packages are developed, compiled, and made available to run from the command line. By default, a ROS1 workspace called `catkin_ws` is available in the home directory. Similarly, a ROS2 workspace called `ament_ws` is available in the home directory. The operating system installed (and therefore version of ROS installed) on your robot dictates whether you'll have a `catkin_ws` or `ament_ws` folder. This guide will show you how to replace existing or create new ROS1/2 workspaces for developing ROS software. ## How Open a terminal and execute the following. ```bash cd ~ git clone https://github.com/hello-robot/stretch4_install cd stretch4_install git pull git checkout main git pull ./stretch_update_ros_workspace.sh ``` ## Wrap up Close your current terminal and open a new one. The new terminal will have automatically activated the ROS workspace(s). Your new ROS workspace is now set up successfully! *** ## Troubleshooting This section provides suggestions for common errors that occur during installation. If you become stuck and don't find an answer here, please email us or contact us through [the forum](https://forum.hello-robot.com/). ### UV not found failure If you see the errors regarding the `uv` CLI not being found in your log file (from `~/stretch_user/log/stretch_create_ament_workspace._log.txt`), follow the [uv installation instructions](https://docs.astral.sh/uv/#getting-started) and then try updating the ROS workspace again. ### Rosdep failure on RTabMap After a failure, if you see the following error in your log file (from `~/stretch_user/log/stretch_create_ament_workspace._log.txt`): ``` ERROR: the following rosdeps failed to install apt: command [sudo -H apt-get install -y ros-humble-rtabmap-ros] failed ``` Open a terminal, run `sudo apt install ros-humble-rtabmap-ros`, and then try updating the ROS workspace again. ### 'Conflicting ROS version sourced' error If you are seeing the following error: ``` ########################################### CREATING WORKSPACE at ########################################### [...] Ensuring correct version of ROS is sourced... Cannot create workspace while a conflicting ROS version is sourced. Exiting. ``` The ROS workspace is not created because the check that a conflicting ROS version isn't already sourced has failed. For example, if you're creating an ROS2 Ament workspace, but ROS1 Noetic was previously sourced in the same environment, the check will error out since the new ROS2 workspace would fail to find its dependencies correctly in this environment. Sourcing a version of ROS typically happens using the following command: `source /opt/ros//setup.bash`. If you ran this command to source a conflicting version previously, simply open a new terminal and the new environment won't have the conflicting ROS version sourced. If you didn't run this command and you're still getting the error, it's likely because the command exists in the `~/.bashrc` dotfile. Every new bash shell (i.e. the terminal you open when searching for 'Terminal' in system applications) runs the commands in the `~/.bashrc` dotfile. Look at the bottom of this dotfile for this command, comment it out temporarily, and open a new terminal. This new shell environment should have no trouble creating the ROS workspace. ### 'ROS\_DISTRO was set before' warning If you are seeing the following warning: ``` ROS_DISTRO was set to '' before. Please make sure that the environment does not mix paths from different distributions. ``` Multiple versions of ROS are being sourced in the same environment. This is known to cause issues with the `rosdep` tool, and might cause issues elsewhere as well. If you haven't explicitly sourced conflicting versions by using the `source /opt/ros//setup.bash` (a variant on this command could look like `source ~//develop/setup.bash`) command twice, then it's likely that one or two versions of ROS are implicitly being sourced in the `~/.bashrc` dofile. Every new bash shell (i.e. the terminal you open when searching for 'Terminal' in system applications) runs the commands in the `~/.bashrc` dotfile. Look at the bottom of this dotfile for the `source` command and ensure conflicting versions aren't being sourced. *** All materials are Copyright 2020-2026 by Hello Robot Inc. Hello Robot and Stretch are registered trademarks. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.hello-robot.com/stretch4_install/docs/ros_workspace.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.