ROS2 설치 오류, 우분투와 맥에서 자주 막히는 5가지

ROS2 설치 오류는 일부 환경에서는 OS 버전, 저장소 키, 환경 변수 문제에서 생깁니다. 우분투와 맥에서 처음 ROS2를 깔 때 일부 환경에서는 마주치는 다섯 가지 상황과 확인 순서를 정리했습니다.

ROS2 설치 오류는 도구 자체의 버그보다 OS 버전 궁합, 저장소 키, 환경 변수 세 가지에서 일부 환경에서는 발생합니다. 이 글은 우분투와 맥에서 처음 ROS2를 설치할 때 자주 막히는 다섯 가지 상황을 증상 → 원인 → 확인 순서로 정리합니다.

로보틱스 공부를 막 시작한 분들이 공식 문서를 그대로 붙여넣었는데도 에러가 뜨는 경우가 많습니다.

시작하기 전에 용어 두 개만 짚고 갑니다.

• ROS2: 로봇 소프트웨어를 만들 때 쓰는 오픈소스 프레임워크입니다. 센서·모터·알고리즘을 부품처럼 조립하게 해줍니다.
• 터미널: 검은 화면에 명령어를 직접 입력해서 컴퓨터를 조작하는 창입니다. 맥은 "터미널" 앱, 우분투는 Ctrl+Alt+T로 열립니다.

목차

1. 설치 전에 반드시 확인할 세 가지
2. 에러 1: "GPG error" 또는 저장소 키 관련 실패
3. 에러 2: "Unable to locate package ros-humble-desktop"
4. 에러 3: "command not found: ros2" — 설치는 됐는데 명령어가 없음
5. 에러 4: 맥에서 설치가 안 되거나 공식 지원이 애매할 때

설치 전에 반드시 확인할 세 가지

ROS2를 깔기 전에 다음 세 가지를 먼저 확인하면 오류의 80%는 미리 피할 수 있습니다. 공식 문서가 요구하는 조합을 무시하고 최신 OS에 최신 ROS2를 얹으려다 실패하는 경우가 압도적으로 많습니다.

확인 항목	왜 중요한가	어디서 확인
OS 버전 (우분투)	ROS2 배포판마다 지원 우분투 버전이 정해져 있음	lsb_release -a
CPU 아키텍처 (맥)	인텔 맥과 애플 실리콘(M1~) 지원이 다름	애플 로고 → 이 Mac 정보
인터넷/방화벽	저장소 키·패키지 다운로드에 필요	사내망·학교망은 특히 주의

ROS2는 배포판(Humble, Iron, Jazzy 등)마다 지원하는 우분투 버전이 딱 정해져 있습니다. 이걸 확인하지 않고 최신 우분투에 오래된 배포판을 얹으면 첫 명령어부터 막힙니다.

정확한 매칭은 ROS2 공식 문서(docs.ros.org)의 각 배포판 페이지 상단 "Supported Platforms"에서 확인하는 것이 가장 안전합니다.

💡 지금 쓰는 우분투 버전이 특정 ROS2 배포판과 안 맞으면 답은 둘 중 하나입니다. 우분투를 바꾸든가, ROS2 배포판을 바꾸든가. 억지로 붙이면 반드시 어딘가에서 터집니다.

에러 1: "GPG error" 또는 저장소 키 관련 실패

이 에러는 ROS2 패키지를 받아오는 저장소를 우분투가 "신뢰할 수 없다"고 거부할 때 나옵니다. 설치 초반 apt update 단계에서 가장 흔하게 만나는 문제입니다.

증상은 대체로 이런 식입니다.

GPG error: http://packages.ros.org/ros2/ubuntu ...
The following signatures couldn't be verified

원인은 일부 환경에서는 셋 중 하나입니다.

• 공식 GPG 키를 등록하지 않고 저장소부터 추가함
• 키 등록 명령어를 복사하다 중간이 잘렸음
• 예전에 설치를 시도했다가 남은 이전 키와 충돌함

해결 순서는 공식 문서의 키 등록 명령을 처음부터 다시 한 번 실행하는 것입니다. curl로 키를 받아 /usr/share/keyrings/에 저장하는 그 명령입니다. 여기서 중요한 건 명령어를 한 줄로 통째로 복사해야 한다는 점입니다. 여러 줄로 나뉘어 붙으면 중간이 잘려 키가 반쪽만 등록됩니다.

그래도 안 되면 이전에 시도한 흔적을 지웁니다.

sudo rm /usr/share/keyrings/ros-archive-keyring.gpg
sudo rm /etc/apt/sources.list.d/ros2.list

이 두 명령은 예전에 등록됐던 ROS2 키 파일과 저장소 목록 파일을 삭제합니다. 지운 뒤 공식 문서의 등록 절차를 처음부터 다시 밟으면 일부 환경에서는 해결됩니다.

에러 2: "Unable to locate package ros-humble-desktop"

sudo apt install ros-humble-desktop을 실행했는데 패키지를 찾을 수 없다는 메시지가 뜨는 상황입니다. ROS2 설치 튜토리얼에서 가장 좌절스러운 순간 중 하나죠.

원인은 세 가지 중 하나입니다.

1. 저장소는 추가했는데 sudo apt update를 안 함
2. 우분투 버전과 ROS2 배포판이 안 맞음 (예: 우분투 20.04에 Jazzy)
3. 배포판 이름을 잘못 씀 (humble ↔ Humble, 대소문자 실수)

확인 순서는 이렇게 갑니다.

lsb_release -a

이 명령은 지금 쓰는 우분투 버전을 알려줍니다. 여기서 나온 버전이 설치하려는 ROS2 배포판의 공식 지원 목록에 있는지 먼저 확인합니다.

지원 목록에 있는데도 안 잡히면 저장소가 제대로 등록됐는지 봅니다.

cat /etc/apt/sources.list.d/ros2.list

이 명령은 ROS2 저장소 주소가 우분투에 등록됐는지 보여줍니다. 파일이 없거나 비어 있으면 저장소 추가 단계를 건너뛴 겁니다.

에러 3: "command not found: ros2" — 설치는 됐는데 명령어가 없음

설치는 무사히 끝났는데 ros2 명령을 치면 "command not found"가 뜹니다. 이건 설치 자체는 성공했고, 환경 변수만 설정이 안 된 상태입니다.

ROS2는 설치 후 매번 "이제부터 이 셸에서 ROS2를 쓰겠다"고 선언하는 절차가 필요합니다. 이걸 소싱(sourcing) 이라고 부릅니다. 비유하자면, 도구는 창고에 다 넣어뒀는데 작업대에 아직 안 꺼내둔 상태예요.

임시로는 이 명령을 실행하면 됩니다.

source /opt/ros/humble/setup.bash

이 명령은 현재 터미널 창에만 ROS2 환경을 활성화합니다. 창을 닫으면 다시 풀립니다. 매번 치기 귀찮으면 셸 설정 파일(~/.bashrc)에 이 줄을 추가해두면 됩니다.

echo "source /opt/ros/humble/setup.bash" >> ~/.bashrc

여기서 humble 부분은 본인이 설치한 배포판 이름으로 바꿔야 합니다. Jazzy를 설치했다면 jazzy로 씁니다.

💡 zsh을 쓰는 분은 .bashrc가 아니라 ~/.zshrc에 넣어야 합니다. 맥이나 커스터마이징한 우분투 환경에서 흔한 실수입니다.

에러 4: 맥에서 설치가 안 되거나 공식 지원이 애매할 때

ROS2는 리눅스(우분투) 우선이고, 맥 지원은 배포판마다 상태가 다릅니다. 실제로 macOS 지원은 "Tier 3"로 분류되는 배포판이 많은데, 이는 공식 바이너리가 제공되지 않고 소스 빌드를 해야 한다는 뜻입니다.

맥 사용자가 선택할 수 있는 현실적인 길은 세 가지입니다.

방법	난이도	언제 추천
Docker로 ROS2 실행	낮음	학습·튜토리얼 목적
UTM/Parallels로 우분투 가상머신	중간	시뮬레이터도 돌리고 싶을 때
macOS 네이티브 소스 빌드	높음	굳이 맥에서 개발해야 할 때

가장 무난한 건 Docker 방식입니다. Docker는 컴퓨터 안에 "작은 우분투 상자"를 띄워서 그 안에서 ROS2를 돌리는 도구예요. 맥의 파일이나 성능에 크게 영향을 안 주면서 리눅스 환경을 그대로 쓸 수 있습니다.

애플 실리콘(M1 이후) 맥이라면 특히 Docker 방식이 편합니다. 네이티브 빌드는 아키텍처 관련 에러를 하나씩 잡아야 해서 초심자에게는 권하지 않습니다.

에러 5: colcon build 단계에서 무너지는 경우

여기까지 왔다면 ROS2 자체는 잘 깔린 상태입니다. 문제는 내가 만든 워크스페이스를 빌드할 때 생깁니다. colcon build(콜콘 빌드 — ROS2에서 프로젝트를 컴파일하는 명령)를 실행하면 에러가 우수수 쏟아지는 상황이죠.

일부 환경에서는 원인 세 가지입니다.

• colcon이 설치 안 됨: ROS2 본체와 별도로 설치해야 합니다. sudo apt install python3-colcon-common-extensions
• 의존성 패키지 누락: rosdep이라는 도구로 필요한 라이브러리를 한 번에 설치할 수 있습니다
• 워크스페이스 폴더 구조 문제: src/ 폴더 안에 패키지를 넣고, src와 같은 위치에서 빌드 명령을 실행해야 합니다

워크스페이스 구조는 이런 모양이어야 합니다.

ros2_ws/
  ├── src/
  │    └── my_package/
  └── (build 명령은 여기서)

빌드 명령은 ros2_ws 폴더 안에서 실행합니다. src 안에 들어가서 실행하면 "패키지를 찾을 수 없다"는 에러가 나옵니다.

의존성 문제는 이렇게 잡습니다.

rosdep install --from-paths src --ignore-src -r -y

이 명령은 src 폴더 안 모든 패키지가 필요로 하는 라이브러리를 자동으로 설치해줍니다. 처음 프로젝트를 클론받았을 때 꼭 한 번 실행하는 게 좋습니다.

에러가 안 잡힐 때 확인 순서

여러 개를 동시에 뒤지지 말고 위에서 아래로 하나씩 봅니다. 로봇 소프트웨어는 층이 많아서, 아래층이 무너지면 위층은 다 무너집니다.

• ☐우분투 버전과 ROS2 배포판이 공식 지원 조합인가
• ☐GPG 키와 저장소가 정상 등록됐는가 (/etc/apt/sources.list.d/ros2.list 확인)
• ☐sudo apt update 시 에러 없이 끝나는가
• ☐source /opt/ros/[배포판]/setup.bash 후 ros2 --help가 뜨는가
• ☐colcon과 rosdep이 별도로 설치돼 있는가

각 배포판의 최신 설치 절차와 지원 OS는 ROS2 공식 문서 docs.ros.org의 해당 배포판 페이지가 정답입니다. 블로그 글은 참고용이고, 명령어를 그대로 복사할 곳은 공식 문서여야 합니다.

다음에 해보면 좋을 것

ROS2가 무사히 깔렸다면 다음 단계는 turtlesim입니다. 화면에 거북이 한 마리가 나오는 튜토리얼인데, 노드·토픽·서비스 같은 ROS2 핵심 개념을 시각적으로 익히기에 이만한 게 없습니다. 공식 튜토리얼에서 "Beginner: CLI tools" 챕터부터 시작하면 됩니다.

설치에서 막히면 일부 환경에서는 위 다섯 가지 안에서 해결됩니다. 에러 메시지를 통째로 검색창에 넣기 전에, OS 버전 궁합 → 저장소 키 → 환경 변수 순서로 먼저 훑어보는 습관을 들이면 로보틱스 공부의 첫 관문이 훨씬 매끄러워집니다.

함께 보면 좋은 글

• SLAM 쉽게 설명 — 로봇은 어떻게 길을 외울까
• 유니트리 G1 휴머노이드 리뷰 — 중국 로봇 어디까지 왔나
• 가정용 휴머노이드 로봇 가격 2026 — 살 수 있는 모델 정리