Ros2 Dependency Management

Step-by-Step Workflows

Workflow 1: Install All Workspace Dependencies (Recommended Initial Setup)

Complete dependency installation for the workspace.

1. Navigate to workspace root:

   cd <workspace_root>
   

2. Run automated dependency installation:

   ./scripts/ros-dep.sh
   

   This script automatically:

   • Runs rosdep update (updates package registry)
   • Installs all tool dependencies from package.xml files
   • Installs all C++ runtime/build dependencies
   • Ensures system dependencies are satisfied

3. Verify installation completed without errors (check final output)

4. Installation is complete; proceed to Python venv setup if needed

Workflow 2: Set Up Python Virtual Environment

Isolate Python development dependencies from system Python.

1. Sync the workspace environment:

   uv sync
   

2. Activate virtual environment:

   source .venv/bin/activate
   

3. Verify installation:

   python3 -m pytest --version
   

4. Deactivate when done:

   deactivate
   

Workflow 3: Update ROS Dependency Cache

Refresh rosdep package registry (required after ROS updates).

1. Update rosdep cache:

   rosdep update
   

2. Verify update completed:

   rosdep list | head -20
   

Workflow 4: Add C++ Dependency to Package

Add a new C++ library to a package's build/runtime dependencies.

1. Edit package's package.xml:

   nano packages/runtime/<package_name>/package.xml
   

2. Add dependency in appropriate section:

   <!-- For build-time dependencies -->
   <build_depend>new_library</build_depend>
   
   <!-- For runtime dependencies -->
   <run_depend>new_library</run_depend>
   
   <!-- For both build and runtime -->
   <depend>new_library</depend>
   

3. Install the new dependency:

   rosdep install --from-paths packages/runtime/<package_name> --ignore-src -y
   

4. Rebuild the package:

   source scripts/setup.bash
   python3 -m colcon build --packages-select <package_name>
   

Workflow 5: Add Python Package Dependency

Add Python package to development or production use.

For Development Dependencies (pytest, docs, linting):

1. Add the package to the appropriate dependency group in pyproject.toml

2. Re-sync the environment:

   uv sync
   

For Production Dependencies (used by package code):

1. Edit package's setup.py or package.xml:

   # For setup.py-based packages:
   nano packages/runtime/<package_name>/setup.py
   

2. Add to install_requires list in setup.py:

   install_requires=[
       'existing-package>=1.0',
       'new-package>=2.0',
   ]
   

   OR edit package.xml for rosdep-managed dependencies:

   <build_depend>python3-new-package</build_depend>
   <run_depend>python3-new-package</run_depend>
   

3. Rebuild the package:

   source scripts/setup.bash
   python3 -m colcon build --packages-select <package_name>
   

Workflow 6: Troubleshoot Missing Dependency

Resolve "package not found" or "library not found" errors.

1. Identify the missing package from error message

2. Search rosdep registry:

   rosdep search <package_name>
   

3. If found in rosdep, add to appropriate package.xml or setup.py

4. If not in rosdep:

   • Check if available via pip: pip search <package_name>
   • Or check GitHub/documentation for installation instructions
   • Add as custom dependency with full installation steps

5. Re-install dependencies and rebuild:

   ./scripts/ros-dep.sh
   source scripts/setup.bash
   python3 -m colcon build --packages-up-to <package_name>
   

Dependency File Locations

Common Dependency Management Commands

# Update rosdep registry
rosdep update

# Search for available package
rosdep search <package_name>

# Check if dependency is satisfied
rosdep check --from-paths packages/runtime/<package_name>

# Install dependencies for specific path
rosdep install --from-paths packages/runtime/<package_name> --ignore-src -y

# List all installed system dependencies
rosdep list | grep "^python3"

# Sync workspace dependencies
uv sync

# Activate Python venv
source .venv/bin/activate

# Show installed packages
python3 -m pip list

Troubleshooting

References

• See the dependency management guide in your project documentation or official ROS 2 docs for detailed workflows
• See the official rosdep reference documentation for rosdep commands and options
• Optionally use an ./scripts/ros-dep.sh helper script in your repository for automated installation
• Refer to package.xml templates in ROS 2 documentation or your project for dependency configuration examples