rustup으로 Rust 툴체인 관리하기

Rust를 처음 시작할 때 공식 사이트에서 안내하는 대로 설치 스크립트를 실행하면 rustup이라는 도구가 함께 깔립니다. 처음에는 “Rust 설치 프로그램”쯤으로 생각하고 넘어가기 쉬운데, 사실 rustup은 그보다 훨씬 많은 일을 해요. 컴파일러 버전을 바꾸거나 nightly 기능을 잠깐 써보거나 팀 전체의 Rust 버전을 맞추거나 WebAssembly로 크로스 컴파일하는 것까지 전부 rustup이 담당합니다.

이번 글에서는 rustup의 설치부터 툴체인 관리, 컴포넌트와 타겟 설정, 팀 단위 버전 고정까지 살펴보겠습니다.

rustup이 뭔가요?

rustup은 Rust의 공식 툴체인 설치 및 관리 도구입니다. 여기서 “툴체인”이란 Rust 컴파일러(rustc)와 패키지 매니저(cargo), 표준 라이브러리, 각종 개발 도구를 묶어서 부르는 말이에요.

“그냥 apt install rustc나 brew install rust로 설치하면 안 되나요?”라고 생각하실 수 있는데, 가능은 하지만 차이가 큽니다. 패키지 매니저로 설치하면 해당 배포판이 제공하는 특정 버전 하나만 쓸 수 있어요. 보통 최신 버전보다 뒤처져 있고, stable과 nightly를 오가며 쓸 수도 없죠. 크로스 컴파일용 타겟을 추가하거나 rust-analyzer 같은 컴포넌트를 관리하는 것도 불편하고요.

rustup은 이런 한계를 해결해줍니다. 여러 버전의 툴체인을 동시에 깔아두고 자유롭게 전환할 수 있고, 프로젝트마다 다른 버전을 지정할 수도 있어요. Rust 공식 팀이 관리하니까 새 버전이 나오면 바로 받을 수 있다는 것도 장점이고요.

설치하기

아직 Rust를 설치하지 않았다면 공식 설치 스크립트를 실행하면 됩니다.

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

이 스크립트가 rustup을 설치하고, rustup이 다시 기본 툴체인(stable)을 설치하는 구조예요. 설치가 끝나면 rustup, rustc, cargo를 모두 사용할 수 있습니다.

macOS에서 Homebrew로 설치하는 방법도 있는데, rustup 공식 사이트에서는 위의 셸 스크립트 방식을 권장합니다. Homebrew를 통해 설치하면 Homebrew가 관리하는 Rust와 rustup이 관리하는 Rust가 충돌할 수 있거든요.

설치가 잘 되었는지 확인해볼게요.

rustup --version

rustup 1.28.1 (f9edccde0 2025-03-05)
info: This is the version for the rustup toolchain manager, not the rustc compiler.
info: The currently active `rustc` version is `rustc 1.85.1 (4eb161250 2025-03-15)`.

버전 정보가 나오면 정상적으로 설치된 겁니다.

업데이트하기

Rust는 6주마다 새 stable 버전이 나옵니다. rustup으로 설치한 툴체인은 rustup update 한 줄이면 최신 버전으로 업데이트할 수 있어요.

rustup update

info: syncing channel updates for 'stable-aarch64-apple-darwin'
info: latest update on 2025-03-18, rust version 1.85.1 (4eb161250 2025-03-15)
info: downloading component 'cargo'
info: downloading component 'rust-std'
info: downloading component 'rustc'

  stable-aarch64-apple-darwin updated - rustc 1.85.1 (4eb161250 2025-03-15) (from rustc 1.84.0)

info: cleaning up downloads & tmp directories

stable만 업데이트하고 싶다면 rustup update stable, nightly만 업데이트하려면 rustup update nightly로 특정 채널만 지정할 수도 있습니다.

rustup 자체도 업데이트가 필요할 때가 있는데, 보통 rustup update를 실행하면 함께 업데이트됩니다. 명시적으로 rustup만 업데이트하고 싶다면 rustup self update를 쓰면 돼요.

툴체인 관리하기

rustup을 쓰는 가장 큰 이유가 바로 여러 툴체인을 동시에 관리할 수 있다는 거예요. 현재 설치된 툴체인 목록을 확인해봅시다.

rustup toolchain list

stable-aarch64-apple-darwin (default)
nightly-aarch64-apple-darwin

기본 설치에서는 stable만 있지만 nightly 툴체인을 추가로 설치할 수 있습니다.

rustup toolchain install nightly

특정 버전이 필요하다면 버전 번호를 직접 지정할 수도 있어요.

rustup toolchain install 1.82.0

기본 툴체인을 변경하려면 rustup default 명령을 씁니다.

rustup default stable

일시적으로 다른 툴체인을 사용하고 싶을 때는 + 문법이 편리합니다. Cargo 명령어 앞에 +툴체인이름을 붙이면 그 한 번만 해당 툴체인으로 실행돼요.

# nightly 컴파일러로 빌드
cargo +nightly build

# 특정 버전으로 테스트
cargo +1.82.0 test

“nightly에서만 되는 기능을 잠깐 테스트해보고 싶은데 평소에는 stable을 쓰고 싶다”는 상황에서 아주 유용합니다.

더 이상 필요 없는 툴체인은 제거해서 디스크 공간을 절약할 수 있어요.

rustup toolchain uninstall 1.82.0

컴포넌트 관리하기

Rust 툴체인에는 컴파일러와 Cargo 외에도 여러 컴포넌트가 포함될 수 있습니다. rustup을 통해 필요한 컴포넌트를 추가하거나 제거할 수 있어요.

현재 설치된 컴포넌트를 확인하려면 이렇게 합니다.

rustup component list --installed

cargo-aarch64-apple-darwin
clippy-aarch64-apple-darwin
rust-docs-aarch64-apple-darwin
rust-std-aarch64-apple-darwin
rustc-aarch64-apple-darwin
rustfmt-aarch64-apple-darwin

자주 사용하는 컴포넌트를 소개하면, clippy는 코드 품질을 높여주는 린트 도구이고, rustfmt는 코드를 공식 스타일 가이드에 맞춰 자동으로 포매팅해주는 도구입니다. rust-analyzer는 에디터에서 자동 완성, 타입 추론, 리팩터링 같은 기능을 제공하는 LSP 서버예요. rust-src는 표준 라이브러리 소스 코드인데, rust-analyzer가 표준 라이브러리 내부를 분석할 때 필요합니다.

컴포넌트를 추가하려면 rustup component add를 씁니다.

rustup component add rust-analyzer
rustup component add rust-src

nightly 툴체인에 컴포넌트를 추가하려면 --toolchain 옵션을 붙이면 돼요.

rustup component add clippy --toolchain nightly

최근 버전의 rustup으로 Rust를 설치했다면 clippy와 rustfmt는 이미 기본으로 포함되어 있을 가능성이 높아요. rust-analyzer와 rust-src는 에디터 환경을 제대로 갖추려면 직접 추가해주는 게 좋습니다.

크로스 컴파일 타겟 설정하기

rustup으로 크로스 컴파일 타겟도 관리할 수 있습니다. 다른 플랫폼용 바이너리를 빌드하고 싶을 때 해당 타겟의 표준 라이브러리를 추가하면 돼요.

현재 설치된 타겟을 확인해볼게요.

rustup target list --installed

aarch64-apple-darwin

기본적으로는 현재 시스템의 타겟만 설치되어 있습니다. WebAssembly로 빌드하고 싶다면 이렇게 타겟을 추가합니다.

rustup target add wasm32-unknown-unknown

Linux 바이너리를 macOS에서 빌드하고 싶다면 해당 타겟을 추가하면 돼요.

rustup target add x86_64-unknown-linux-gnu

타겟을 추가한 후에는 cargo build에 --target 옵션을 붙여서 빌드할 수 있습니다.

cargo build --target wasm32-unknown-unknown

사용 가능한 모든 타겟 목록은 rustup target list로 확인할 수 있는데, 지원하는 플랫폼이 상당히 많습니다. ARM 임베디드부터 WebAssembly, Windows, Linux, macOS까지 다양한 아키텍처를 지원해요.

참고로 타겟을 추가한다고 바로 크로스 컴파일이 되는 건 아닐 수 있습니다. C 라이브러리에 의존하는 크레이트가 있다면 해당 플랫폼의 링커와 시스템 라이브러리도 별도로 설치해야 해요. 순수 Rust 코드만으로 이루어진 프로젝트라면 타겟 추가만으로 바로 빌드할 수 있습니다.

rust-toolchain.toml로 팀 전체 버전 고정하기

혼자 개발할 때는 rustup default로 기본 툴체인을 지정해두면 충분하지만 팀에서 일한다면 모든 사람이 같은 Rust 버전을 쓰도록 맞춰야 합니다. “내 컴퓨터에서는 빌드되는데?”를 방지하려면요 😅

rust-toolchain.toml 파일을 프로젝트 루트에 만들어두면 rustup이 자동으로 해당 버전을 사용합니다.

[toolchain]
channel = "1.85.1"
components = ["rustfmt", "clippy", "rust-analyzer"]
targets = ["wasm32-unknown-unknown"]

이 파일을 Git에 커밋해두면 팀원이 프로젝트를 클론해서 cargo build를 실행하는 순간 rustup이 알아서 지정된 버전을 설치하고 필요한 컴포넌트와 타겟까지 추가해줍니다. 따로 뭘 설정할 필요가 없어요.

channel에는 "stable", "nightly", "1.85.1" 같은 값을 쓸 수 있어요. stable로 지정하면 팀원마다 다른 stable 버전을 쓸 수 있으니 정확한 버전 번호를 명시하는 게 재현 가능한 빌드에 좋습니다.

nightly가 필요한 프로젝트라면 날짜를 고정하는 것도 방법이에요.

[toolchain]
channel = "nightly-2026-03-15"
components = ["rustfmt", "clippy"]

nightly는 날마다 바뀌니까 날짜를 고정해두지 않으면 어느 날 갑자기 빌드가 깨질 수 있거든요.

rust-toolchain 파일(확장자 없이)에 채널 이름만 적는 레거시 방식도 있는데, 컴포넌트와 타겟까지 지정할 수 있는 TOML 형식이 더 낫습니다.

rustup override로 디렉토리별 툴체인 설정하기

프로젝트마다 다른 Rust 버전이 필요한 상황이 있어요. 한 프로젝트는 stable로 개발하고 다른 프로젝트는 nightly 기능이 필요한 경우죠. rust-toolchain.toml이 없는 프로젝트라면 rustup override로 디렉토리별 툴체인을 지정할 수 있습니다.

# 현재 디렉토리에서 nightly 사용
rustup override set nightly

이러면 해당 디렉토리와 하위 디렉토리에서는 항상 nightly가 사용됩니다. 다른 디렉토리에서는 여전히 기본 툴체인이 적용되고요.

현재 설정된 override 목록을 확인하려면 이렇게 합니다.

rustup override list

override를 해제하려면 unset을 씁니다.

rustup override unset

rustup이 툴체인을 선택하는 데는 우선순위가 있어요. RUSTUP_TOOLCHAIN 환경 변수가 가장 높고, 그다음이 cargo +toolchain 문법, rustup override, rust-toolchain.toml 파일, 마지막으로 rustup default 순입니다. 보통은 rust-toolchain.toml로 프로젝트 버전을 고정하는 게 투명하고 공유도 쉬워서 override보다 권장돼요.

rustup doc으로 오프라인 문서 보기

Rust를 설치하면 표준 라이브러리 문서가 로컬에 함께 설치됩니다. rustup doc 명령어로 브라우저에서 바로 열 수 있어요.

# 표준 라이브러리 문서 열기
rustup doc

# 특정 모듈 문서 바로 열기
rustup doc std::collections::HashMap

# Rust 레퍼런스 문서
rustup doc --reference

# Cargo 문서
rustup doc --cargo

인터넷이 없어도 문서를 볼 수 있다는 게 포인트예요. 비행기 안에서 코딩하거나 네트워크가 불안정할 때 유용하죠. 설치된 Rust 버전에 딱 맞는 문서를 보여주기 때문에 버전 불일치로 헷갈릴 일도 없고요.

rustup show로 현재 환경 확인하기

현재 Rust 환경이 어떻게 구성되어 있는지 한눈에 보고 싶을 때 rustup show를 쓰면 됩니다.

rustup show

Default host: aarch64-apple-darwin
rustup home:  /Users/dale/.rustup

installed toolchains
--------------------
stable-aarch64-apple-darwin (default)
nightly-aarch64-apple-darwin

active toolchain
----------------
stable-aarch64-apple-darwin (default)
rustc 1.85.1 (4eb161250 2025-03-15)

설치된 툴체인 목록과 현재 활성화된 툴체인, rustc 버전까지 보여줍니다. 빌드가 이상하게 동작할 때 제일 먼저 확인해볼 만한 명령어예요.

어떤 툴체인이 왜 선택되었는지 더 자세히 알고 싶다면 rustup which도 있어요.

rustup which rustc

/Users/dale/.rustup/toolchains/stable-aarch64-apple-darwin/bin/rustc

실제로 어떤 경로의 rustc가 실행되는지 보여주니까 의도한 툴체인이 맞는지 확인할 때 좋아요.

실무 팁

써보면서 알게 된 몇 가지 팁을 공유할게요.

새 프로젝트를 시작할 때 rust-toolchain.toml을 가장 먼저 만드세요. Rust 버전과 필요한 컴포넌트를 처음부터 명시해두면 다른 팀원이 합류하거나 CI를 설정할 때 “어떤 버전을 써야 하지?”라는 질문이 사라집니다.

CI에서도 rust-toolchain.toml이 있으면 편해요. GitHub Actions의 dtolnay/rust-toolchain 액션이 이 파일을 자동으로 읽어서 맞는 버전을 설치해줍니다. CI와 로컬이 같은 버전을 쓰게 되니까 “CI에서만 실패하는” 문제가 줄어들어요.

rustup update는 주기적으로 실행해주세요. 새 Rust 버전에는 컴파일 속도 개선이나 새 API, 버그 수정이 들어 있어요. clippy도 Rust 버전마다 새 린트가 추가되니까 업데이트 자체가 코드 품질을 높일 기회가 됩니다.

디스크 공간이 부족하다면 rustup toolchain uninstall로 안 쓰는 툴체인을 정리하세요. 툴체인 하나가 수백 MB를 차지하기 때문에 오래된 버전을 쌓아두면 금방 부족해져요. rustup show로 목록 확인하고 필요 없는 것들을 지우면 됩니다.

마치며

rustup은 Rust를 설치하는 첫 단계이면서 이후 개발 환경 전체를 관리하는 도구입니다. 단순한 설치 프로그램이 아니라 툴체인 버전 관리, 컴포넌트 설치, 크로스 컴파일 타겟, 팀 단위 버전 고정까지 다 맡아요.

rust-toolchain.toml 하나로 팀 전체의 개발 환경을 통일할 수 있고, rustup update로 최신 버전을 유지하면서 clippy로 코드 품질을 높이고 cargo fmt로 스타일을 통일하는 흐름이 자연스럽게 만들어집니다.

더 자세한 내용은 rustup 공식 문서를 참고하세요.