파이썬 러스트 바인딩 개발 환경 구축하기(Maturin + PyO3)

파이썬 러스트 바인딩(Python-Rust Binding)은 파이썬의 높은 생산성과 러스트의 강력한 성능을 결합할 수 있는 개발 방식으로 최근 많은 관심을 받고 있다. 파이썬(Python)은 풍부한 라이브러리 생태계와 뛰어난 개발 생산성을 제공하지만, 순수 파이썬(Pure Python)으로 구현된 대량의 반복 연산이나 계산 집약적인 알고리즘에서는 인터프리터 특성상 성능 제약이 발생할 수 있다. 이를 해결하기 위해 전체 애플리케이션은 생산성이 높은 파이썬으로 구성하고, 성능이 중요한 핵심 연산만 러스트(Rust)로 구현하여 호출하는 하이브리드 아키텍처가 널리 활용되고 있다.

러스트는 C/C++급의 강력한 성능을 제공하면서도 높은 안정성을 갖춘 프로그래밍 언어다. 실행 속도는 매우 빠르면서도 메모리 오류나 멀티스레드 관련 버그를 컴파일 단계에서 미리 검출할 수 있어 최근 시스템 소프트웨어와 고성능 애플리케이션 개발에 널리 활용되고 있다. 따라서 파이썬-러스트 바인딩을 활용하면 파이썬의 높은 개발 생산성을 유지하면서도 성능과 안정성을 동시에 확보할 수 있다.

이번 글에서는 파이참(PyCharm) 환경에서 Maturin과 PyO3를 이용해 파이썬-러스트 바인딩 개발 환경을 만드는 과정을 단계별로 정리해 보았다.

프로젝트 시작하기: 환경 구축

🔗 jetbrains 공식 홈페이지: [https://www.jetbrains.com/pycharm/download/?section=windows 바로가기]

파이참이 설치되어 있지 않다면 설치

Pycharm 프로젝트 만들기

먼저 개발 환경인 파이참을 실행하고 프로젝트를 생성한다. 이때 러스트의 명명 규칙(Naming Convention)을 반드시 준수해야 바인딩 빌드 시 오류나 경고를 피할 수 있다.

먼저 파이참에서 프로젝트를 생성한다.

• [File] > [New Project…] 메뉴를 선택한다.
• [Pure Python]을 선택한 뒤 프로젝트 경로와 이름을 입력하고 [Create]를 클릭한다.

프로젝트 이름 명명 규칙

파이썬은 보통 PyRustHybrid처럼 대소문자를 섞어 쓰지만, 러스트는 프로젝트명에 대문자가 포함되면 경고(Warning)를 발생시킨다. 빌드가 안 되는 것은 아니지만, 경고를 방지하기 위해 소문자와 언더바(_)만 조합하여 이름을 짓는 것이 관례다.

나의 테스트 프로젝트명: py_rust_hybrid

필수 도구 설치 및 초기화

러스트 코드를 파이썬 라이브러리로 빌드하고 바인딩하기 위해서는 몇 가지 필수 도구가 필요하다. 파이참 터미널(Terminal)에서 아래 명령어를 순서대로 실행한다.

Step 1. Maturin 설치

Maturin은 파이썬 환경에서 러스트 프로젝트를 빌드하고 파이썬 라이브러리로 패키징(바인딩)해 주는 핵심 도구다.

#터미널에서 다음 명령어를 실행
pip install maturin

#터미널에서 다음 명령어를 실행
pip install maturin

Step 2. 러스트 프로젝트 초기화

#터미널에서 다음 명령어를 실행
maturin init

#터미널에서 다음 명령어를 실행
maturin init

명령어를 실행하면 옵션 선택 창이 나타난다. 키보드 방향키로 PyO3 항목으로 이동한 뒤 엔터(Enter)를 누른다. 참고로 크레이트(Crate)는 러스트에서 라이브러리나 패키지를 의미하는 단위다. PyO3는 파이썬과 러스트를 연결하는 대표적인 크레이트로, 러스트 코드를 파이썬에서 직접 호출할 수 있도록 해준다.

Step 3. Rustup 설치

실제 소스 코드를 컴파일할 러스트 공식 표준 도구들을 설치할 차례다.

• 🔗 Rustup 공식 다운로드 주소: [https://www.rust-lang.org/tools/install]
• Download rustup-init.exe (x64) 파일을 다운로드하여 설치한다.
• 터미널 창이 뜨면 기본 옵션인 1번 (Proceed with standard installation (default))을 입력하고 엔터를 눌러 설치를 완료한다.

설치가 정상적으로 끝났다면, 터미널을 실행하여 아래 명령어로 버전을 확인한다.

#설치 제대로 됐는지 확인
rustc --version # Rust 컴파일러 (소스 코드를 실행 파일로 빌드)
cargo --version # Rust의 빌드 시스템 및 패키지 매니저
rustup --version # Rust 버전 및 툴체인 관리 도구

#설치 제대로 됐는지 확인
rustc --version # Rust 컴파일러 (소스 코드를 실행 파일로 빌드)
cargo --version # Rust의 빌드 시스템 및 패키지 매니저
rustup --version # Rust 버전 및 툴체인 관리 도구

📌 Rustup을 통해 관리하는 이유 러스트는 언어 특성상 버전 업데이트가 잦다. 타 언어와 달리 컴파일러만 따로 설치하지 않고 rustup을 사용하는 것이 공식 표준이다. 나중에 새 버전이 출시되어도 rustup update 명령 한 줄로 모든 환경을 최신 상태로 유지할 수 있어 매우 편리하다.

바인딩 빌드 테스트 (Maturin Develop)

모든 개발 도구 세팅이 완료되었다면 파이썬 러스트 바인딩이 제대로 호환되는지 첫 빌드를 수행한다.

maturin develop

maturin develop

• 이 명령어를 실행하면 maturin이 시스템에 설치된 rustc와 cargo를 자동으로 찾아내어 프로젝트를 빌드하고, 현재 파이썬 가상환경(venv)에 라이브러리로 즉시 연결(설치)해 준다. 이제 파이썬 코드에서 러스트 함수를 import할 수 있는 상태가 된다.
• 만약 에러가 발생한다면 환경 변수가 아직 반영되지 않은 것일 수 있으므로, 파이참을 완전히 종료 후 재실행하여 명령어를 다시 입력한다.

프로젝트 구조 이해하기

바인딩 환경 구성이 성공하면 프로젝트 디렉토리에 여러 파일이 생성된다. 각 파일의 역할을 파악해 두면 추후 관리가 수월해진다.

• Cargo.toml – 러스트 프로젝트의 설계도. 프로젝트 이름, 버전, 그리고 바인딩에 필요한 pyo3 등의 외부 라이브러리(Crate)를 정의하는 곳이다. maturin이 이 파일을 보고 Rust 코드를 어떻게 파이썬 모듈로 만들지 결정한다.
• src/ – 모든 러스트 소스 코드가 저장되는 폴더다.
• src/lib.rs – 파이썬 러스트 바인딩의 핵심. 파이썬에서 호출하여 사용할 러스트 함수들과 모듈 구조를 이 파일에 정의한다. 파이썬으로 치면 __init__.py와 메인 로직이 융합된 형태다.
• pyproject.toml – 파이썬 배포 및 빌드 설정. 파이썬 환경에게 “이 프로젝트는 빌드할 때 maturin이라는 도구를 사용해 러스트 코드를 컴파일하고 바인딩한다”는 약속을 적어둔 설정 파일이다. 이 파일이 있어야 나중에 파이썬 환경에서 pip install . 같은 명령어로 설치가 가능
• target/ – 컴파일이 완료된 파일들이 저장되는 결과물 폴더다. 빌드가 반복될수록 용량이 커지므로 절대 수동으로 건드리지 않는다. Git에 코드를 올릴 때 .gitignore에 필수로 등록해야 할 1순위 폴더다.

기본 테스트 코드 실행하기

환경 구축이 완료되었으니 프로젝트가 정상 작동하는지 기본 예제로 테스트를 진행한다.

Step 1. 파이썬 테스트 파일 생성

파이참 프로젝트 폴더를 우클릭한 뒤 [New] > [Python File]을 선택하여 main.py 파일을 생성한다.

Step 2. 러스트 기본 코드 확인 (src/lib.rs)

use pyo3::prelude::*;

/// A Python module implemented in Rust.
#[pymodule]
mod py_rust_hybrid {
    use pyo3::prelude::*;

    /// Formats the sum of two numbers as string.
    #[pyfunction]
    fn sum_as_string(a: usize, b: usize) -> PyResult<String> {
        Ok((a + b).to_string())
    }
}

use pyo3::prelude::*;

/// A Python module implemented in Rust.
#[pymodule]
mod py_rust_hybrid {
    use pyo3::prelude::*;

    /// Formats the sum of two numbers as string.
    #[pyfunction]
    fn sum_as_string(a: usize, b: usize) -> PyResult<String> {
        Ok((a + b).to_string())
    }
}

maturin init을 통해 생성된 src/lib.rs 파일에는 이미 다음과 같은 기본 예제 코드가 작성되어 있다.

두 수의 합을 계산하여 문자열로 반환하는 간단한 로직이다.

• PyResult<String>: 러스트의 데이터를 파이썬의 문자열 데이터(str)로 안전하게 넘겨주기 위한 래퍼(Wrapper) 타입이다.

Step 3. 파이썬에서 호출 및 실행 (main.py)

이미 앞선 단계에서 maturin develop 명령어로 빌드를 마쳤기 때문에, 파이썬에서 즉시 임포트(import)하여 사용할 수 있다.

main.py에 코드를 작성

import py_rust_hybrid

# 러스트의 sum_as_string 함수 호출
# Rust의 usize는 파이썬의 int로 자동 매핑됩니다.
result = py_rust_hybrid.sum_as_string(10, 20)

# 2. 결과 확인
print(f"러스트에서 받은 결과값: {result}")
print(f"결과값의 타입: {type(result)}")

# 3. 만약 문자열이 맞는지 확인
if result == "30":
    print("성공! 러스트에서 문자열로 잘 변환되어 넘어왔다.")

import py_rust_hybrid

# 러스트의 sum_as_string 함수 호출
# Rust의 usize는 파이썬의 int로 자동 매핑됩니다.
result = py_rust_hybrid.sum_as_string(10, 20)

# 2. 결과 확인
print(f"러스트에서 받은 결과값: {result}")
print(f"결과값의 타입: {type(result)}")

# 3. 만약 문자열이 맞는지 확인
if result == "30":
    print("성공! 러스트에서 문자열로 잘 변환되어 넘어왔다.")

파이썬 스크립트를 실행하면 성공 메시지가 출력되며 바인딩이 정상 작동함을 확인할 수 있다.

마무리

지금까지 PyCharm 환경에서 Maturin과 PyO3를 활용하여 파이썬-러스트 바인딩 개발 환경을 구축하는 과정을 살펴보았다.

사실 개인적으로는 설치 과정이 생각보다 간단하다는 점이 인상적이었다. 예전에는 새로운 개발 언어나 컴파일러 환경을 구성할 때 PATH 설정부터 각종 환경 변수 문제까지 예상치 못한 오류를 많이 겪었던 기억이 있다. 특히 C/C++ 계열 개발 환경은 설치보다 환경 설정에 더 많은 시간을 쓰는 경우도 적지 않았다.

하지만 러스트는 공식 도구인 rustup이 워낙 잘 만들어져 있어서 설치 과정이 상당히 매끄럽게 진행되었다. 컴파일러(rustc), 패키지 매니저(cargo), 버전 관리까지 하나의 도구로 통합 관리되기 때문에 별도의 복잡한 설정 없이도 바로 개발을 시작할 수 있었다. 실제로 이번 테스트 환경 역시 예상보다 훨씬 빠르게 구축할 수 있었고, 중간에 환경 변수나 PATH 문제로 시간을 허비하는 일도 거의 없었다.

또한 Maturin과 PyO3의 조합 역시 매우 직관적이었다. 몇 개의 명령어만으로 러스트 코드를 파이썬 모듈로 빌드하고 바로 import하여 사용할 수 있다는 점은 상당히 인상적이었다. 덕분에 파이썬의 높은 생산성을 유지하면서도 성능이 필요한 부분만 러스트로 구현하는 하이브리드 개발 방식이 생각보다 훨씬 현실적인 선택지라는 것을 체감할 수 있었다.

이번 글에서는 개발 환경 구축과 기본 바인딩 테스트까지만 진행했지만, 다음 글에서는 실제 성능 비교 벤치마크를 통해 순수 파이썬과 러스트 바인딩 간의 차이를 확인해 보고, 실무에서 활용할 수 있는 다양한 예제도 함께 살펴볼 예정이다.

파이썬의 편리함과 러스트의 성능을 동시에 얻고 싶다면, Python-Rust Binding은 충분히 한 번 도전해 볼 만한 기술이라고 생각한다.

Python + Rust 바인딩 시리즈

• 파이썬 러스트 바인딩 개발 환경 구축하기(Maturin + PyO3)
• 파이썬 러스트 바인딩 성능 최적화 실험 (NumPy + Rayon + SIMD + Release Build)
• 파이썬 러스트 바인딩 최적화 심화편 1: SIMD와 AVX2