ROS2 Humble에서 colcon build 오류 해결

대상: Ubuntu 22.04 + ROS2 Humble 환경에서 colcon build를 실행할 때 자꾸 실패해서, 어떤 순서로 문제를 찾아야 할지 정리하고 싶은 사람
환경 예시:

  • Ubuntu 22.04 + ROS2 Humble (APT 설치)
  • 워크스페이스: ~/ros2_ws/src
  • 빌드 명령: colcon build --symlink-install

ROS2를 처음 시작하면 공식 튜토리얼에 이렇게 적혀 있다.

colcon build --symlink-install

그런데 막상 실행해보면, 상황에 따라 이런 오류들이 튀어나온다.

  • colcon: command not found
  • ModuleNotFoundError: No module named 'em'
  • c++: fatal error: Killed signal terminated program cc1plus (메모리 부족)
  • 이미 /opt/ros/humble에 있는 예제 패키지와 이름이 겹친다는 WARNING
  • 혹은 아예 빌드가 중간에 멈추고, 어떤 패키지 실패 로그만 잔뜩 남는 경우

이 글에서는 “어떤 에러든 다 커버하는 만능 해답”이 아니라,

  1. colcon 관련 문제를 범주별로 나눠서 보는 방법
  2. 초보자가 가장 자주 겪는 대표적인 colcon build 오류 3종
  3. 각 오류에 대한 원인 + 해결 순서
  4. Notion 에러 / 문제 로그에 정리할 때 템플릿

을 정리해 둬서, 다음에 비슷한 상황이 왔을 때
“당황하지 않고 순서대로 체크할 수 있도록” 만드는 게 목표다.

1. colcon build 오류는 크게 3단계로 나눠보면 편하다

colcon 문제가 생겼을 때는, 보통 아래 세 단계 중 어디에서 막히는지부터 확인하면 좋다.

  1. colcon 자체가 실행이 안 되는 경우
    • colcon: command not found
    • colcon 설치/환경 문제
  2. 빌드 시스템/환경 쪽 문제
    • ModuleNotFoundError: No module named 'em'
    • CMake/패키지 의존성 누락, Python 모듈 누락 등
  3. 패키지 코드/리소스 쪽 문제
    • 특정 패키지만 실패
    • “build/install/log 지우고 다시 빌드하니 된다”는 유형

이 글에서는 실제 사례를 기준으로 각 단계에서 자주 나오는 패턴을 같이 본다.

2. 케이스 1 – colcon: command not found (colcon 설치/환경 문제)

2-1. 증상

터미널에서 colcon build를 치면:

colcon: command not found

2-2. 원인

  • colcon 패키지가 설치되어 있지 않거나,
  • 설치되어 있지만 현재 쉘 환경(PATH)에서 찾지 못하거나,
  • 다른 파이썬 venv 안에서 실행 중이라 경로가 꼬인 경우

2-3. 해결 순서

  1. colcon 설치 확인
sudo apt update
sudo apt install -y python3-colcon-common-extensions
  1. 환경 재적용

ROS2 Humble를 APT로 설치했다면, 보통 아래를 ~/.bashrc에 넣어 두었을 것이다.

source /opt/ros/humble/setup.bash

현재 터미널에서 즉시 적용하려면:

source /opt/ros/humble/setup.bash

을 다시 실행한다.

  1. PATH 확인
which colcon

대략 /usr/bin/colcon 또는 /usr/local/bin/colcon 같은 경로가 나온다면 정상이다.

3. 케이스 2 – ModuleNotFoundError: No module named 'em' (Python 모듈 누락)

3-1. 증상

일부 패키지를 빌드할 때 아래와 비슷한 에러가 뜰 수 있다.

Traceback (most recent call last):
  File "/opt/ros/humble/lib/rosidl_generator_dds_idl/rosidl_generator_dds_idl", line 6, in <module>
    from rosidl_generator_dds_idl import generate_dds_idl
  ...
  File "/opt/ros/humble/local/lib/python3.10/dist-packages/rosidl_cmake/__init__.py", line 22, in <module>
    import em
ModuleNotFoundError: No module named 'em'
...
gmake: *** [Makefile:146: all] Error 2

이 에러는 ROS2의 메시지/서비스 자동 생성 코드에서
템플릿 엔진으로 쓰는 empy / em 모듈이 없어서 발생한다.

3-2. 원인

  • ROS2에서 메시지/IDL 생성 시 em 파이썬 모듈이 필요하지만,
  • 현재 Python 환경(특히 venv 내부)에 em이 설치되어 있지 않은 경우
  • 또는 ROS2 설치 환경과 다른 Python venv에서 빌드를 시도하는 경우

3-3. 해결 순서

  1. 가급적 Python venv 밖에서 빌드하기

ROS2 Humble를 APT로 설치한 경우,
처음에는 가상환경을 쓰지 않고 기본 시스템 Python에서 빌드하는 것이 덜 꼬인다.

  1. 필요한 패키지 설치

Ubuntu 기준으로는 다음 패키지가 핵심이다.

sudo apt install -y python3-empy

추가로, 상황에 따라 아래 패키지도 같이 설치해두면 좋다.

sudo apt install -y python3-colcon-common-extensions python3-rosdep
  1. venv를 꼭 써야 한다면
  • venv 안에서 pip install empy를 해도 되지만,
  • ROS2 관련 CMake/python 경로가 섞일 수 있으니
    “처음에는 venv 없이 빌드 → 필요해지면 신중하게 venv 도입”하는 순서를 추천한다.
  1. 빌드 캐시 삭제 후 재빌드

문제가 계속된다면, 워크스페이스 상위에서:

rm -rf build install log
colcon build --symlink-install

로 캐시를 지우고 다시 빌드해 보는 것도 좋다.
(실제 ROS 커뮤니티 Q&A에서도 이 방법으로 해결되는 사례가 많다.)

4. 케이스 3 – c++: fatal error: Killed signal (메모리 부족)

4-1. 증상

특히 라즈베리 파이, Jetson 같은 SBC나 메모리가 적은 장비에서
무거운 패키지를 빌드할 때 이런 에러가 뜰 수 있다.

c++: fatal error: Killed signal terminated program cc1plus
compilation terminated.
gmake[2]: *** [CMakeFiles/xxx.dir/src/yyy.cpp.o] Error 1
gmake[1]: *** [CMakeFiles/Makefile2:139: CMakeFiles/xxx.dir/all] Error 2
gmake: *** [Makefile:146: all] Error 2

4-2. 원인

  • C++ 컴파일(cc1plus) 중에 RAM을 많이 사용해서
    커널 OOM(Out Of Memory) 킬러가 컴파일 프로세스를 강제 종료한 상태
  • 특히 텐서/SLAM/시뮬레이션/로봇 미들웨어(예: gazebo_ros2_control 등) 빌드 시 자주 발생

4-3. 해결 순서

  1. 동시에 빌드하는 작업 수 줄이기

기본 colcon build는 CPU 코어 수에 맞춰 병렬 빌드를 수행한다.
메모리가 부족할 경우, 병렬 처리 수를 줄이면 한 번에 먹는 RAM이 줄어든다.

colcon build --symlink-install --parallel-workers 1
  1. 스왑(Swap) 공간 늘리기
  • Jetson, 라즈베리 파이처럼 RAM이 적은 장비에서는
    스왑 파일을 늘려주면 빌드 성공률이 올라간다.
  • 다만 스왑은 디스크 I/O가 느리므로, 빌드 시간은 길어질 수 있다.
  1. 불필요한 프로세스/서비스 종료
  • GUI, 브라우저, 무거운 IDE 등을 잠시 꺼두면
    컴파일에 쓸 수 있는 RAM이 늘어난다.
  1. 실패 패키지만 선택적으로 빌드

어떤 패키지가 무거운지 대략 감이 온다면,
필요한 패키지만 따로 빌드하는 것도 방법이다.

colcon build --packages-select my_light_package

5. 공통 팁 – colcon 빌드가 꼬였을 때 “리셋”하는 방법

패키지 코드 변경, 의존성 설치 변경, Python 환경 변경 등을 거치다 보면
build, install, log 폴더 내용이 꼬여서 이상한 에러가 계속 나오는 경우도 있다.

이럴 때 가장 간단한 리셋 방법은:

rm -rf build install log
colcon build --symlink-install

이다.

  • build/ : 중간 빌드 결과
  • install/ : 워크스페이스 설치 결과
  • log/ : 이전 빌드 로그

를 모두 지우고, 깨끗한 상태에서 다시 빌드하는 효과가 있다.

관련 게시물

댓글 남기기