Skip to main content
🔧 Build GuideUpdated June 2026

colcon Build Guide 2026Selective Builds · symlink-install · Tests · Mixins

Complete 2026 guide to colcon, the ROS 2 standard build tool. Covers workspace setup, selective package builds (packages-select, packages-up-to, packages-above), --symlink-install for instant Python iteration, CMake build types, parallel workers, colcon test, COLCON_IGNORE files, build logs, and mixins for repeatable workflows.

colcon buildpackages-selectsymlink-installcolcon testCOLCON_IGNORE

Common Flags Reference

FlagWhat it does
--packages-select <pkg>Build only this package (no deps)
--packages-up-to <pkg>Build package + all its dependencies
--packages-above <pkg>Build package + everything that depends on it
--packages-ignore <pkg>Skip this package
--symlink-installSymlink Python files (no rebuild on .py change)
--cmake-args <args>Pass flags to CMake (e.g. -DCMAKE_BUILD_TYPE=Release)
--parallel-workers NLimit concurrent package builds (saves RAM)
--mixin <name>Apply a named preset of flags
--event-handlers console_direct+Show stdout/stderr live during build
--continue-on-errorKeep building other packages even if one fails

Workspace Setup & Selective Builds

First Build — Workspace Setup

colcon is the standard build tool for ROS 2. Create a workspace, clone packages, build, and source the install overlay.

bash
# Install colcon and build extensions
sudo apt install python3-colcon-common-extensions python3-colcon-mixin

# Add useful colcon mixins (optional but recommended)
colcon mixin add default https://raw.githubusercontent.com/colcon/colcon-mixin-repository/master/index.yaml
colcon mixin update default

# Create workspace structure
mkdir -p ~/ros2_ws/src
cd ~/ros2_ws

# Clone your package
git clone https://github.com/my_org/my_package.git src/my_package

# Install package dependencies (fetches from rosdep)
rosdep install --from-paths src --ignore-src -r -y

# Build everything in the workspace
colcon build

# Source the install overlay (run in every new shell, or add to .bashrc)
source install/setup.bash

💡 Always source install/setup.bash AFTER each build — it updates the environment with the latest installed packages.

Selective Build — Build Only What You Need

colcon can build a subset of packages. This is much faster when you only changed one package.

bash
# Build a single package
colcon build --packages-select my_package

# Build a package AND everything it depends on
colcon build --packages-up-to my_package

# Build a package AND everything that depends on it
colcon build --packages-above my_package

# Build multiple specific packages
colcon build --packages-select my_robot my_msgs my_bringup

# Skip specific packages
colcon build --packages-ignore heavy_simulation_pkg benchmark_pkg

# Build packages that match a regex
colcon build --packages-select-regex "^my_robot.*"

symlink-install & Build Types

--symlink-install for Python Development

With --symlink-install, Python files are symlinked into install/ instead of copied. Changes to .py files take effect immediately — no rebuild needed.

bash
# Build with symlinks (Python changes are instant — no rebuild)
colcon build --symlink-install

# Rebuild a single Python package with symlinks
colcon build --packages-select my_python_pkg --symlink-install

# When NOT to use --symlink-install:
# - C++ packages: compiled binaries, symlinks don't help
# - Production builds: symlinks mean editing src/ changes the install
# - CI/CD: use full copy for reproducibility

# After adding new Python files (new modules/entry_points), you still need:
colcon build --packages-select my_pkg --symlink-install

# Verify the symlink is in place
ls -la install/my_python_pkg/lib/my_python_pkg/

ℹ️ --symlink-install only affects Python (ament_python) packages. C++ packages always compile a binary regardless.

CMake Build Type and Parallel Jobs

Control build type (Release vs Debug) and parallelism for faster C++ builds.

bash
# Build in Release mode (optimized — use for benchmarks / production)
colcon build --cmake-args -DCMAKE_BUILD_TYPE=Release

# Build in Debug mode (symbols — use for gdb / valgrind)
colcon build --cmake-args -DCMAKE_BUILD_TYPE=Debug

# Use RelWithDebInfo (optimized + debug symbols — best of both)
colcon build --cmake-args -DCMAKE_BUILD_TYPE=RelWithDebInfo

# Limit parallel package builds (saves RAM on low-memory systems)
colcon build --parallel-workers 2

# Combine: selective + release + 4 parallel jobs
colcon build   --packages-select my_robot   --cmake-args -DCMAKE_BUILD_TYPE=Release   --parallel-workers 4

# Use ccache to speed up repeated C++ builds
sudo apt install ccache
colcon build --cmake-args -DCMAKE_CXX_COMPILER_LAUNCHER=ccache

Testing

Running Tests with colcon test

colcon test runs all tests (ament_cmake, pytest, gtest) in the workspace. Use colcon test-result to see the results.

bash
# Run all tests in the workspace
colcon test

# Run tests for specific packages only
colcon test --packages-select my_package my_msgs

# Run tests with verbose output (shows individual test names)
colcon test --event-handlers console_direct+

# Show test results after running
colcon test-result

# Show only failures
colcon test-result --all | grep -E "FAIL|ERROR"

# Show verbose test result details
colcon test-result --verbose

# Run a specific pytest test file directly
cd build/my_package
pytest test/test_my_node.py -v

# Run tests in parallel (default: sequential within a package)
colcon test --parallel-workers 4

✅ colcon test creates test logs in log/test_<package_name>/. Check them for detailed pytest/gtest output.

Workflow Tips — IGNORE, Logs & Mixins

COLCON_IGNORE — Skip Packages

Place a COLCON_IGNORE file in a directory to prevent colcon from building it. Useful for example packages or in-progress work.

bash
# Skip a package by placing COLCON_IGNORE inside it
touch src/heavy_simulation_pkg/COLCON_IGNORE
touch src/deprecated_pkg/COLCON_IGNORE

# colcon will now ignore those directories
colcon build  # builds everything EXCEPT the marked directories

# Also works for entire subdirectories:
touch src/experimental/COLCON_IGNORE  # skips all packages under experimental/

# Remove to re-enable
rm src/heavy_simulation_pkg/COLCON_IGNORE

Logs and Diagnostics

colcon logs each package build. Use these commands to diagnose failures.

bash
# Show verbose build output for all packages
colcon build --event-handlers console_direct+

# Show only stderr (warnings and errors)
colcon build --event-handlers console_stderr+

# Check the log file for a failed package
cat log/latest_build/my_package/stderr.log
cat log/latest_build/my_package/stdout.log

# List build log directories
ls log/

# Print build times
colcon build --event-handlers console_package_list+

# Clean the build and install for one package (force full rebuild)
rm -rf build/my_package install/my_package
colcon build --packages-select my_package

# Clean everything
rm -rf build install log

⚡ The log/ directory contains symlinks to latest_build, latest_test — always check there first when debugging.

Useful colcon Mixins

Mixins are pre-configured flag sets you can apply by name. They save typing common flag combinations.

bash
# List available mixins
colcon mixin show

# Build in release with debug symbols (most common mixin)
colcon build --mixin release-with-debug

# Build with compile_commands.json (for IDEs and clang-tidy)
colcon build --mixin compile-commands

# Build faster with ccache
colcon build --mixin ccache

# Combine mixins
colcon build --mixin release-with-debug ccache compile-commands

# Custom .colcon/defaults.yaml in your workspace root
# avoids having to type flags every time:
cat > .colcon/defaults.yaml << 'EOF'
build:
  symlink-install: true
  cmake-args:
    - "-DCMAKE_BUILD_TYPE=RelWithDebInfo"
  event-handlers:
    - console_cohesion+
EOF
colcon build  # applies defaults.yaml automatically

Related Guides

ROS 2 Getting Started

Workspace setup from scratch

ROS 2 Parameters

Configure nodes via YAML

Docker for ROS 2

Containerize your colcon workspace