# ROS2 Humble 전용 Python 환경 설정

#### Python 버전 선정의 중요성

ROS2 Humble은 내부적으로 Python 3 계열을 활용하여 빌드 및 실행 환경을 구성한다. 따라서 호환성이 검증된 Python 버전을 선택하는 것은 매우 중요하다. 일반적으로 Ubuntu 22.04와 함께 제공되는 Python 3.10을 권장하며, 특정 패키지 호환성 문제 등으로 인해 Python 3.8\~3.10을 병행해서 쓰기도 한다. 작업 환경에 따라 다음 사항을 유의해야 한다.

* \*\*ROS2 빌드 툴(colcon 등)\*\*이 제대로 동작하려면 최소한 ROS2에서 공식 지원하는 Python 버전을 사용해야 한다.
* 시스템에 여러 버전의 Python이 설치되어 있을 경우, `python` 혹은 `pip` 명령을 입력했을 때 어느 버전이 기본값인지 확인해야 한다.

다음과 같은 셸 명령으로 기본 Python 버전을 간단히 확인할 수 있다.

```
python --version
```

만약 결과가 원하는 버전이 아니라면, `$ which python` 명령으로 어떤 경로의 파이썬이 우선순위를 가지는지 확인하고, 필요한 경우 환경 변수를 조정하거나 심볼릭 링크를 재설정해야 한다.

#### 시스템 Python 사용 vs 별도 Python 환경 구성

ROS2 Humble 개발 시 시스템 기본 Python을 사용하는 방법과, 별도의 가상환경(virtual environment) 혹은 `pyenv`, `conda` 등을 활용하여 독립된 Python 환경을 구성하는 방법이 있다. 프로젝트 규모가 커지거나, 다양한 Python 패키지 버전을 실험해야 하는 경우에는 독립된 환경 구성이 추천된다.

별도 환경을 사용하면 다음과 같은 장점이 있다.

* ROS2와 관련 없는 Python 패키지와 충돌을 방지할 수 있다.
* ROS2 Humble용 패키지들과 별도의 실험용 패키지를 분리하여 유지할 수 있다.
* 시스템 단에서 Python 패키지를 잘못 제거하여 의존성 문제가 발생하는 일을 최소화할 수 있다.

#### Python 가상환경 구성 (venv)

가장 간단하게 별도의 Python 환경을 구성하는 방법은 `venv` 모듈을 활용하는 것이다. Python 3.6 이상에 포함되어 있으며, 프로젝트별 독립 환경을 만들기에 적합하다.

1. 원하는 위치(예: `~/ros2_env/humble`)에 디렉터리를 만든다.
2. `venv` 모듈을 사용해 가상환경을 초기화한다.
3. 생성된 환경을 활성화한다.

아래 예시는 `~/ros2_env/humble`라는 폴더에 ROS2 Humble 전용 가상환경을 생성하는 과정이다.

```
mkdir -p ~/ros2_env/humble
cd ~/ros2_env/humble
python3 -m venv .venv
source .venv/bin/activate
```

이제부터 이 셸 세션에서는 `.venv` 폴더에 있는 독립된 Python 인터프리터와 패키지 관리자를 사용하게 된다. `pip`, `python` 등을 실행하면 모두 이 가상환경을 통해 동작한다.

#### 가상환경을 통한 ROS2 Humble 개발

가상환경을 생성하고 활성화한 뒤에는 필요한 ROS2 관련 Python 패키지를 설치할 수 있다. 예를 들어 ROS2 패키지 빌드를 돕는 `colcon`이나 ROS 빌드 의존성 관리를 위한 `rosdep` 등을 아래와 같이 설치한다.

```
pip install colcon-common-extensions
pip install rosdep
```

그리고 ROS2 Humble을 사용하기 위해서는 시스템에 ROS2 Humble 자체가 설치되어 있어야 하며, 보통 `/opt/ros/humble/setup.bash` 등의 셸 스크립트를 통해 ROS2 환경 변수를 가져온다.

```
source /opt/ros/humble/setup.bash
```

이 스크립트를 실행하면 ROS2 Humble이 제공하는 `ros2` 실행 파일, 메시지 타입, 라이브러리, 빌드용 CMake 등 각종 환경 변수가 설정된다.

#### pyenv로 Python 버전 관리하기

만약 프로젝트마다 다른 버전의 Python을 사용해야 한다면, `pyenv`를 고려해볼 수 있다. `pyenv`는 원하는 Python 버전을 소스 빌드 혹은 미리 컴파일된 바이너리로 설치하고, 그 버전들의 우선순위를 지정할 수 있도록 돕는다. ROS2 Humble용으로 Python 3.10 환경을 별도 설치하고, 특정 디렉터리에서만 해당 버전을 사용하도록 설정 가능하다.

`pyenv`를 설치한 뒤 다음과 같은 단계를 거친다.

1. `$ pyenv install 3.10.9` 등으로 원하는 버전 설치
2. `$pyenv global 3.10.9` 혹은 `$ pyenv local 3.10.9`를 통해 기본 파이썬 버전 지정
3. 이후 `python --version`이 원하는 버전을 가리키는지 확인

그리고 `pyenv shell` 명령을 통해 현재 터미널 세션에만 특정 버전을 지정할 수도 있다. 예컨대 다음과 같이 입력하면 현재 세션에서 Python 3.10.9 버전만 사용하도록 고정된다.

```
pyenv shell 3.10.9
```

필요에 따라 venv와 pyenv를 함께 활용하여, ROS2 Humble 전용 Python 버전을 별도로 설치하고 그 위에 venv를 만들어 사용하는 것도 가능하다.

#### 다이어그램 예시

아래는 Python 환경 설정 과정을 간단히 흐름도로 나타낸 예시이다.

{% @mermaid/diagram content="flowchart TD
A("Python 설치 확인") --> B("pyenv 혹은 venv 선택")
B --> C("원하는 Python 버전 설치 혹은 가상환경 생성")
C --> D("ROS2 Humble 환경 세팅( source /opt/ros/humble/setup.bash )")
D --> E("필요한 Python 패키지 설치(pip install)")" %}

#### Python 환경 변수 관리

ROS2 Humble에서 Python을 사용할 때는 다음과 같은 환경 변수가 적절하게 설정되어 있어야 한다. 가상환경이나 별도의 Python 버전을 사용하더라도, ROS2 실행 시에는 내부적으로 관련 환경 변수를 참조하므로 설정이 꼬이지 않도록 주의해야 한다.

* **$PYTHONPATH** Python 모듈 경로를 지정한다. 보통은 ROS2 패키지를 빌드하면 필요한 모듈들이 `install/lib/pythonX.X/site-packages` 아래에 위치한다. ROS2 환경 스크립트를 실행하면 자동으로 $PYTHONPATH에 이 경로가 등록된다. 가상환경을 사용할 경우, 가상환경이 우선되도록 설정된 후 ROS2 환경 스크립트를 불러오는 것이 좋다.
* **$PATH** Python 실행 파일을 비롯한 각종 실행 바이너리를 찾는 경로다. 가상환경을 활성화하면 `$PATH` 맨 앞에 해당 가상환경 내 `bin` 폴더가 자동으로 등록된다. ROS2는 `$PATH` 경로 중에서 `ros2` 명령어(또는 다른 실행 파일)를 검색하게 된다.
* **$LD\_LIBRARY\_PATH** Python 확장 라이브러리가 C++로 구현된 경우 동적 링크 라이브러리를 찾는 경로가 여기에 포함된다. ROS2 설치 스크립트를 실행하면 `/opt/ros/humble/lib`와 유사한 경로가 여기에 등록된다.
* **$CMAKE\_PREFIX\_PATH** ROS2 패키지 빌드 시 CMake를 통해 라이브러리나 헤더 등을 검색할 때 참조한다. ROS2 Humble 설치 스크립트(예: `/opt/ros/humble/setup.bash`)를 실행하면 해당 경로가 자동으로 등록된다.

가상환경을 만들고 활성화한 뒤, 그리고 나서 ROS2 설치 스크립트를 실행하는 방식이 일반적이다. 명령어 순서는 다음과 같다.

```
# (venv 환경 활성화)
source ~/ros2_env/humble/.venv/bin/activate

# ROS2 설치 스크립트
source /opt/ros/humble/setup.bash
```

혹은 이 과정을 편리하게 해주는 별도의 셸 스크립트를 만들어 놓고, 프로젝트 별로 쉽게 로드할 수 있도록 관리하기도 한다.

#### Python 패키지 의존성 관리

ROS2 Python 패키지나 기타 의존성 있는 라이브러리를 프로젝트마다 상이하게 요구할 수 있다. 이를 간편하게 관리하기 위해 `requirements.txt` 또는 `poetry`, `pipenv` 등을 사용하는 방법이 있다.

* **requirements.txt** 프로젝트 루트 디렉터리에 `requirements.txt` 파일을 두고, 필요한 모든 Python 패키지와 버전을 명시해두면 재현 가능성을 높일 수 있다.

```
pip install -r requirements.txt
```

와 같은 방식으로 한 번에 설치 가능하다.

* **pipenv, poetry** 가상환경 관리와 의존성 관리를 통합해서 수행해주는 도구들이다. 가상환경의 생성·활성화부터 배포, 버전 충돌 검사 등을 쉽게 해준다.

ROS2 패키지 의존성 파일과 Python 패키지 의존성 파일을 각각 관리하는 경우가 많다. ROS2 관련 의존성은 `package.xml` 파일을 통해 관리하고, Python 패키지 의존성은 `requirements.txt`나 `pyproject.toml`(poetry) 등을 통해 관리한다.

#### rclpy와 Python 노드 실행

ROS2의 Python 클라이언트 라이브러리인 `rclpy`는 ROS2 Node를 Python으로 작성할 수 있도록 한다. `rclpy`를 정상적으로 사용하기 위해서는 다음을 확인해야 한다.

1. ROS2 Humble 설치(예: `/opt/ros/humble/`)
2. `$PYTHONPATH`, `$LD_LIBRARY_PATH`, `$PATH` 등의 환경 변수 설정
3. Python 3.8 이상(권장 3.10)
4. `rclpy` 패키지가 설치되어 있는지 확인 (ROS2 설치 시 기본 포함되어 있을 가능성이 큼)

파이썬 노드를 실행할 때는 일반적으로

```
ros2 run 패키지명 노드파일이름
```

형태의 명령어를 사용한다. 이때 가상환경에 종속되지 않고 ROS2 설치 스크립트에서 설정한 Python을 기본적으로 활용하는 구조지만, 특정 시점의 쉘 환경이 어떻게 설정되었느냐에 따라 가상환경이 함께 적용될 수도 있다.

직접 Python 스크립트를 실행하려면:

```
source ~/ros2_env/humble/.venv/bin/activate
source /opt/ros/humble/setup.bash
python path/to/your_script.py
```

처럼 순차적으로 환경을 불러온 후, Python 스크립트에 `rclpy`를 import하여 노드를 구동한다.

#### Docker를 통한 Python 환경 격리

프로젝트 규모가 매우 커지거나, 여러 버전의 ROS2나 Python을 동시에 사용해야 하는 경우에는 **Docker 컨테이너**를 활용해 완전히 격리된 환경을 구성하기도 한다. Docker 이미지를 통해 운영체제 버전, Python 버전, ROS2 버전을 특정 상태로 고정할 수 있으므로 협업 및 배포 시 재현성이 높아진다.

1. **Dockerfile** 작성 시 베이스 이미지를 Ubuntu 22.04 기반으로 하거나, 공식 ROS2 Humble 이미지를 사용한다.
2. `RUN apt-get update && apt-get install -y python3 python3-venv ...` 등 필요한 패키지를 설치한다.
3. 컨테이너 내부에서 ROS2 설치 스크립트를 source하고, 필요한 Python 가상환경을 생성해둔다.

이렇게 구성하면, 팀원 간 환경 차이를 줄이고, CI/CD 파이프라인에서 빌드/테스트 자동화를 손쉽게 진행할 수 있다.

#### Python 환경 디버깅 팁

ROS2 Python 환경에서 문제가 발생했을 때 가장 먼저 해야 할 일은 현재 활성화된 Python 환경과 ROS2 환경이 올바르게 설정되었는지 점검하는 것이다. 아래는 몇 가지 확인 절차와 해결 방안이다.

**현재 Python 경로 확인**

```
which python
python --version
```

결과가 기대하는 Python 버전을 가리키는지 반드시 확인해야 한다.

**pip 경로 확인**

```
which pip
pip --version
```

`pip`가 해당 Python 가상환경의 실행 파일인지 확인한다. Python과 pip가 서로 다른 위치를 가리키면 패키지 설치 시 엉뚱한 Python 버전에 반영될 수 있다.

1. **$PYTHONPATH 확인**

   ```
   echo $PYTHONPATH
   ```

   ROS2 메시지나 라이브러리 경로가 누락되었거나, 불필요한 경로가 추가되어 충돌을 일으키는 경우가 있는지 확인한다. 가상환경 활성화 후, ROS2의 setup 스크립트를 다시 실행해야 필요한 경로들이 올바르게 설정된다.

**ROS2 명령 동작 확인**

```
source /opt/ros/humble/setup.bash
ros2 topic list
```

등의 명령을 수행해보고, 에러가 발생하거나 빈 결과가 나온다면 ROS2 환경 변수 설정이 제대로 되지 않았을 가능성을 의심해야 한다.

**가상환경 탈출 및 재활성화**

가상환경이 꼬였다고 판단되면 일단 다음과 같이 탈출(`deactivate`) 후 재활성화 과정을 거친다.

```
deactivate
source ~/ros2_env/humble/.venv/bin/activate
source /opt/ros/humble/setup.bash
```

**라이브러리 충돌 검사**

`import rclpy` 시점에서 에러가 발생한다면, Python과 C/C++ 동적 라이브러리의 버전이 호환되지 않을 수 있다. `$LD_LIBRARY_PATH` 혹은 ROS2 설치 경로에 주의한다.

#### 환경 설정 자동화(.bashrc, .zshrc 등)

매번 셸을 열 때마다 가상환경 활성화와 ROS2 setup 스크립트를 manually 실행하는 것은 번거로울 수 있다. 이를 자동화하기 위해 다음과 같은 방법을 고려할 수 있다.

**.bashrc 혹은 .zshrc 등에 명령어 추가**

```
# ROS2 Humble 환경 자동 설정
source /opt/ros/humble/setup.bash
source ~/ros2_env/humble/.venv/bin/activate
```

단, 다른 프로젝트에서 Python 버전이 다를 수 있으므로, 모든 셸에서 무조건 해당 가상환경을 켜는 것은 부적절할 때가 많다. 필요에 따라 alias를 정의하거나 별도 스크립트를 만들어두는 것이 좋다.

**별도 스크립트 사용**

```
#!/usr/bin/env bash
source ~/ros2_env/humble/.venv/bin/activate
source /opt/ros/humble/setup.bash
```

이런 스크립트를 `ros2_humble_env.sh` 등으로 만들어두고, 작업할 때마다 `source ros2_humble_env.sh` 명령을 실행하면 일괄 설정된다.

#### Conda 환경과의 차이점

`conda`는 데이터 과학 분야에서 많이 사용하는 Python 배포판으로, C/C++ 라이브러리와 Python 패키지를 함께 관리할 수 있는 장점이 있다. ROS2와 conda 환경을 함께 사용하려면 다음 사항을 주의해야 한다.

* conda 환경에서 ROS2 관련 라이브러리가 모두 지원되는지 확인 (일부 ROS2 의존 라이브러리가 conda 채널에 없을 수 있다.)
* `$LD_LIBRARY_PATH` 등 동적 라이브러리 경로가 conda 환경과 충돌하지 않도록 설정
* conda 환경 활성화 후 ROS2 setup 스크립트를 불러오면, conda 환경에서 Python 인터프리터와 ROS2 라이브러리를 동시에 사용할 수 있다.

#### Visual Studio Code와의 연동

VSCode에서 ROS2 프로젝트를 Python 가상환경과 함께 개발하려면 다음과 같은 설정을 고려한다.

**Python Interpreter 설정**:

VSCode 하단의 Python Interpreter 선택 창에서 가상환경의 파이썬 인터프리터(예: `~/ros2_env/humble/.venv/bin/python`)를 선택한다.

**ROS2 Extension**:

ROS2 확장(extension)을 설치하면 ROS 메시지 정의, tf, URDF 등의 기능을 편리하게 이용할 수 있다.

**launch.json 설정**:

Python 노드를 디버깅하거나, 여러 노드를 동시에 실행하려면 VSCode의 `launch.json`

을 커스터마이징한다. 아래는 간단한 예시다.

```json
{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "ROS2 Python Node",
            "type": "python",
            "request": "launch",
            "program": "${workspaceFolder}/my_package/scripts/my_node.py",
            "env": {
                "PYTHONUNBUFFERED": "1"
            },
            "preLaunchTask": "source-ros2"
        }
    ]
}
```

여기서 `"preLaunchTask"` 에 ROS2 설치 스크립트나 가상환경 활성화 스크립트를 연결해두면, 디버깅 시 자동으로 환경이 세팅된다.

#### PyCharm 등 다른 IDE 사용 시 주의사항

PyCharm에서 ROS2 Python 노드를 작성·실행할 때도, 동일하게 원하는 가상환경을 Interpreter로 지정하고 ROS2 setup 스크립트를 실행하는 것을 고려해야 한다.

* **Interpreter 설정** `Settings > Project > Python Interpreter`에서 `~/ros2_env/humble/.venv/bin/python` 경로를 선택한다.
* **터미널 활성화** PyCharm 내장 터미널에서도 동일하게 가상환경이 자동으로 활성화되도록 설정할 수 있다.
* **ROS2 launch 파일 지원** Python launch 파일(`.launch.py`)을 통한 노드 실행 시, PyCharm이 해당 파일을 파이썬 스크립트로 인식하도록 Run Configuration을 커스터마이징해야 한다.