러스트 설치

운영체제에 맞게 rustup과 컴파일 도구를 설치하고 버전 확인·업데이트·삭제·로컬 문서 열람 방법을 익힙니다.

러스트를 처음 시작할 때 가장 많이 막히는 구간은 문법이 아니라 설치와 실행 환경입니다.

명령어 한 줄이 어긋나면 내가 개념을 못 이해한 건가?라는 오해가 생기기 쉽기 때문입니다.

그래서 이 절은 단순 설치 절차를 나열하는 데서 끝나지 않고, 운영체제별로 어디서 실수가 자주 나는지까지 함께 짚어가며 진행합니다.

이번 장에서 배우는 내용은 다음과 같습니다.

각 운영체제(Linux, macOS, Windows)별 러스트 설치법
Hello, world! 프로그램 작성하기
러스트 패키지 매니저 및 빌드 도구인 cargo 사용법

이제 설치 절차와 실행 확인 과정을 순서대로 진행하겠습니다.

Rust 설치를 실제 실행까지 확인하는 흐름

rustup 툴체인→선택 OS 링커 준비/보완→같은 셸 PATH→두 버전→최소 cargo run의 완료 증거가 달라진다.

Rust · install · flowchart

설치는 `cargo run`이 끝날 때 완료된다

rustup은 러스트 툴체인을 맡고, 운영체제의 링커와 네이티브 라이브러리는 별도로 준비합니다. 같은 셸에서 명령 탐색부터 최소 프로그램 실행까지 한 흐름으로 확인합니다.

인터넷과 셸 고정
설치와 확인을 cmd, PowerShell, bash, zsh 중 같은 셸에서 이어갑니다.
rustup 툴체인 설치
rustc, cargo, 표준 라이브러리와 stable 채널을 준비합니다.
운영체제 빌드 도구 확인
Windows는 C++ 워크로드와 SDK, macOS는 Xcode 명령줄 도구, Linux는 GCC나 Clang을 별도로 준비합니다.
같은 셸에서 PATH 확인
명령을 찾지 못하면 새 터미널을 열고 rustc와 cargo가 같은 툴체인을 가리키는지 확인합니다.
컴파일러와 빌드 도구 버전 확인
rustc --version과 cargo --version이 모두 출력되어야 합니다.
cargo run으로 완료 판정
최소 프로젝트의 Hello, world! 출력까지 확인해야 링커를 포함한 실행 환경이 검증됩니다.

명령을 찾지 못함

터미널을 다시 열어 PATH 반영을 확인하고, 설치 때 사용한 셸과 확인 셸을 섞지 않습니다.

링커 오류

러스트 문법보다 운영체제 C/C++ 빌드 도구와 네이티브 라이브러리 누락을 먼저 점검합니다.

Windows 설치 범위

Visual Studio 또는 Build Tools 2022면 충분하며 전체 IDE는 필수가 아닙니다. 영어 언어팩은 오류 공유를 위한 권장 사항입니다.

다운로드 성공만으로는 충분하지 않습니다. 툴체인, 셸, PATH, 운영체제 링커가 함께 맞아야 첫 프로그램이 실행됩니다.

이 예의 조건

본문과 원 도표에 제시된 사례의 입력·조건을 사용합니다. 설명용 수치나 독립 비교 경로는 각 단계에 표시합니다.
현재 상태·값과 전환 근거의 위치는 모든 단계에서 같습니다. 조건이 맞지 않거나 실행되지 않은 경로를 성공한 동작으로 해석하지 않습니다.

관계도의 보충 설명

원 도표의 제목·노드·관계·조건·주석
범위	원문
관계·조건 설명	인터넷/셸→rustup→OS 도구 판정의 7노드다. 준비됨은 OS 보완 단계를 건너뛰어 PATH로 합류하고 아니요는 링커·SDK 보완 뒤 합류한다. PATH→두 버전→최소 cargo run으로 완료한다. 이 예제의 native host 실행 확인이며 다운로드나 버전 출력만으로 완료하지 않는다.
노드·연결선 라벨	준비됨은 보완 단계 건너뜀

예의 값과 변화
관찰·상황	값·보충 정보	변화·이유
툴체인·링커 rustup 툴체인과 선택 OS의 링커를 준비한다.	툴체인: rustc·Cargo 플랫폼 조건: OS에 맞는 링커	Rust 설치 성공과 링크 가능한 환경은 별도 조건이다.
같은 셸 확인 PATH를 새 환경에 반영해 두 버전을 확인한다.	명령: rustc --version / cargo --version 위치: 같은 셸	다른 셸의 PATH가 최소 실행의 환경을 대신하지 않는다.
최소 실행 cargo run으로 빌드·링크·실행을 확인한다.	작업: 최소 Cargo 프로그램 완료 근거: cargo run 결과	버전 문자열만으로 프로그램의 링크·실행 성공을 보장하지 않는다.

Rust 설치를 실제 실행까지 확인하는 흐름

rustup 툴체인→선택 OS 링커 준비/보완→같은 셸 PATH→두 버전→최소 cargo run의 완료 증거가 달라진다.

Rust · install · flowchart

설치는 `cargo run`이 끝날 때 완료된다

인터넷과 셸 고정
설치와 확인을 cmd, PowerShell, bash, zsh 중 같은 셸에서 이어갑니다.
rustup 툴체인 설치
rustc, cargo, 표준 라이브러리와 stable 채널을 준비합니다.
운영체제 빌드 도구 확인
Windows는 C++ 워크로드와 SDK, macOS는 Xcode 명령줄 도구, Linux는 GCC나 Clang을 별도로 준비합니다.
같은 셸에서 PATH 확인
명령을 찾지 못하면 새 터미널을 열고 rustc와 cargo가 같은 툴체인을 가리키는지 확인합니다.
컴파일러와 빌드 도구 버전 확인
rustc --version과 cargo --version이 모두 출력되어야 합니다.
cargo run으로 완료 판정
최소 프로젝트의 Hello, world! 출력까지 확인해야 링커를 포함한 실행 환경이 검증됩니다.

명령을 찾지 못함

터미널을 다시 열어 PATH 반영을 확인하고, 설치 때 사용한 셸과 확인 셸을 섞지 않습니다.

링커 오류

러스트 문법보다 운영체제 C/C++ 빌드 도구와 네이티브 라이브러리 누락을 먼저 점검합니다.

Windows 설치 범위

Visual Studio 또는 Build Tools 2022면 충분하며 전체 IDE는 필수가 아닙니다. 영어 언어팩은 오류 공유를 위한 권장 사항입니다.

다운로드 성공만으로는 충분하지 않습니다. 툴체인, 셸, PATH, 운영체제 링커가 함께 맞아야 첫 프로그램이 실행됩니다.

이 예의 조건

본문과 원 도표에 제시된 사례의 입력·조건을 사용합니다. 설명용 수치나 독립 비교 경로는 각 단계에 표시합니다.
현재 상태·값과 전환 근거의 위치는 모든 단계에서 같습니다. 조건이 맞지 않거나 실행되지 않은 경로를 성공한 동작으로 해석하지 않습니다.

관계도의 보충 설명

원 도표의 제목·노드·관계·조건·주석
범위	원문
관계·조건 설명	인터넷/셸→rustup→OS 도구 판정의 7노드다. 준비됨은 OS 보완 단계를 건너뛰어 PATH로 합류하고 아니요는 링커·SDK 보완 뒤 합류한다. PATH→두 버전→최소 cargo run으로 완료한다. 이 예제의 native host 실행 확인이며 다운로드나 버전 출력만으로 완료하지 않는다.
노드·연결선 라벨	준비됨은 보완 단계 건너뜀

예의 값과 변화
관찰·상황	값·보충 정보	변화·이유
툴체인·링커 rustup 툴체인과 선택 OS의 링커를 준비한다.	툴체인: rustc·Cargo 플랫폼 조건: OS에 맞는 링커	Rust 설치 성공과 링크 가능한 환경은 별도 조건이다.
같은 셸 확인 PATH를 새 환경에 반영해 두 버전을 확인한다.	명령: rustc --version / cargo --version 위치: 같은 셸	다른 셸의 PATH가 최소 실행의 환경을 대신하지 않는다.
최소 실행 cargo run으로 빌드·링크·실행을 확인한다.	작업: 최소 Cargo 프로그램 완료 근거: cargo run 결과	버전 문자열만으로 프로그램의 링크·실행 성공을 보장하지 않는다.

우선 러스트를 설치해야겠죠.

설치는 rustup이라는 러스트 버전 및 러스트 관련 도구를 관리하는 커맨드 라인 도구를 이용할 겁니다.

인터넷이 연결되어 있어야 하니 미리 인터넷 연결을 확인해 주세요.

가능하면 이 단계에서 터미널 종류(cmd, PowerShell, bash/zsh)를 하나로 고정해 두는 것을 권장합니다.

셸마다 경로 표기와 환경 변수 출력 방식이 조금씩 달라, 초반 혼선을 줄이는 데 도움이 됩니다.

Note: rustup 이외에 다른 방법으로 설치하길 원하신다면 기타 러스트 설치 방법 페이지를 참고하시기 바랍니다.

다음은 러스트 컴파일러 최신 stable 버전을 설치하는 내용입니다.

혹여나 이 책을 읽는 시점에, 이 책에서 사용한 버전이 낮아서 걱정되시는 분들을 위해 말씀드리자면, 러스트에는 안정성 보장(stability guarantees)이 적용되어 있습니다.

에러·경고의 표현과 빌드 로그는 컴파일러 버전에 따라 달라질 수 있습니다. 안정성 보장은 같은 에디션의 정상적인 stable Rust 코드를 이어 사용하는 데 도움을 주지만, 외부 크레이트의 버전·지원 타깃·빌드 도구까지 자동으로 고정하지는 않습니다. 예제를 따라 할 때는 edition과 의존성 조건도 확인하고, 의도된 실패 예제는 주변 설명의 규칙과 대조하세요.

커맨드 라인 표기

이번 장을 비롯해 터미널에 명령어를 입력할 일이 많습니다. 입력할 명령어와 출력을 구분하실 수 있도록, 명령어에는 각 행 앞에 $가 붙습니다. $가 붙지 않은 행은 보통 앞선 명령어의 결과를 나타낸다고 보시면 됩니다. 예외적으로, $ 대신 >가 붙은 예제는 Windows 예제입니다. CMD·PowerShell이 다른 곳은 본문의 셸 이름을 따릅니다. $와 >는 프롬프트 표시이므로 명령에 함께 입력하지 않습니다.

`rustup` 설치 - Linux 및 macOS

Linux나 macOS 사용자는 터미널을 열고 다음 명령어를 입력해 주세요.

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

최신 stable 버전 러스트를 설치하는 데 사용할 rustup 도구를 설치하는 명령어입니다. (설치할 때 여러분의 비밀번호를 묻는 메시지가 나타날 수 있습니다.)

설치가 완료되면 다음 문장이 나타납니다.

Rust is installed now. Great!

rustup은 rustc, cargo, 표준 라이브러리 같은 러스트 툴체인을 설치하지만, 운영체제의 링커와 네이티브 라이브러리까지 설치하지는 않습니다.

러스트 컴파일 중 링커를 실행할 수 없다는 에러가 나타나면 플랫폼에 맞는 C/C++ 빌드 도구와 링커를 별도로 설치해야 합니다.

몇 가지 흔히 사용되는 러스트 패키지들이 C 코드를 이용하고 있기 때문에 C 컴파일러가 필요할 수도 있습니다.

macOS에서는 아래와 같이 실행하여 C 컴파일러를 설치할 수 있습니다.

$ xcode-select --install

Linux 사용자는 배포판 문서에 따라 GCC나 Clang을 설치해야 합니다.

예를 들어 우분투 사용자라면 build-essential 패키지를 설치할 수 있습니다.

`rustup` 설치 - Windows

Windows 사용자는 https://www.rust-lang.org/tools/install에서 안내를 따라주시기 바랍니다.

MSVC 타깃으로 빌드하려면 러스트 툴체인과 별도로 C++ 링커와 Windows SDK가 필요합니다. 현재 안내에 맞춰 Visual Studio 2022 또는 Build Tools for Visual Studio 2022를 사용하면 되며, 전체 Visual Studio IDE를 설치할 필요는 없습니다.

Visual Studio Installer에서는 다음 항목을 확인합니다.

‘C++ 데스크톱 개발’
Windows 10 혹은 11 SDK
오류 메시지를 다른 사람과 공유하기 쉬운 영어 언어팩(권장 사항이며 컴파일 필수 조건은 아닙니다)

이후부터는 cmd.exe와 PowerShell에서 공통으로 사용할 수 있는 명령어만 사용할 예정이며, 서로 다른 부분이 있을 경우엔 따로 명시하겠습니다.

트러블 슈팅

러스트가 제대로 설치되었는지 확인하는 방법은 다음과 같습니다.

$ rustc --version
$ cargo --version

rustc와 cargo가 모두 버전 정보를 출력해야 합니다. rustc의 최신 stable 버전 정보는 다음 포맷대로 나타나며, 나타난 정보는 순서대로 버전 숫자, 커밋 해시(hash), 커밋 날짜입니다.

rustc x.y.z (abcabcabc yyyy-mm-dd)

버전 확인 뒤에는 최소 프로젝트를 실제로 빌드하고 실행해 툴체인과 운영체제 빌드 도구가 함께 동작하는지 확인합니다.

$ cargo new hello-rust
$ cd hello-rust
$ cargo run

기본 프로그램의 Hello, world! 출력까지 보이면 설치가 완료된 것입니다.

설치 결과를 스스로 판정하기

rustc와 cargo 버전은 둘 다 보이는데 cargo run이 링커를 찾을 수 없다는 오류로 끝났다고 가정하세요. Rust 컴파일러가 없다는 뜻일까요, Hello 실행까지 확인한 상태일까요? 재설치하기 전에 어느 범위부터 확인해야 할까요?

완료 기준의 풀이

버전 출력은 현재 셸이 두 도구를 찾았다는 증거입니다. 실행 파일을 만드는 마지막 링크와 실제 실행까지 성공했다는 증거는 아닙니다. 이 경우에는 선택 타깃에 맞는 운영체제 링커·SDK·빌드 도구와 그 탐색 경로를 먼저 확인합니다. 컴파일러 진단과 링커 오류를 구분하면 무조건 러스트 툴체인 전체를 다시 설치하는 일을 줄일 수 있습니다.

정보가 보이지 않는다면 여러분의 %PATH% 시스템 변수에 러스트가 포함되어 있는지 확인해 주세요.

Windows CMD에서는 다음과 같이 확인합니다.

> echo %PATH%

PowerShell에서는 다음과 같이 확인합니다.

> echo $env:Path

Linux와 macOS에서는 다음과 같이 확인합니다.

$ echo $PATH

위 항목을 모두 점검했는데도 문제가 계속되면 한국 러스트 사용자 그룹 디스코드에서 유사 사례와 해결 절차를 참고할 수 있습니다.

영어가 능숙한 분들은 커뮤니티 페이지에서 다른 러스타시안(Rustacean, 러스트 사용자들 스스로를 부르는 재미있는 별명입니다)들을 만나볼 수 있을 겁니다.

업데이트 및 삭제

rustup으로 러스트를 설치했다면 최신 버전 업데이트도 간편합니다.

셸에서 다음 명령어를 실행합니다.

$ rustup update

rustup과 러스트를 삭제하는 방법은 다음과 같습니다.

$ rustup self uninstall

업데이트와 삭제는 설치가 끝난 뒤에도 반복해서 만나게 되는 관리 명령입니다.

어떤 상황에서 어떤 rustup 명령을 확인하면 되는지 아래처럼 묶어 두면 도구 체인의 상태를 빠르게 점검할 수 있습니다.

Rust · tools · command matrix

도구의 책임과 완료 신호를 구분한다

rustup은 툴체인을 관리하고, rustc는 컴파일하며, cargo는 프로젝트를 빌드하고 실행합니다. 설치 완료는 두 버전 출력과 최소 cargo run으로 판정합니다.

도구 · 명령 · 책임 · 확인 기준
도구 또는 명령	책임	대표 사용	확인 기준
`rustup`	stable, beta, nightly 같은 러스트 툴체인과 구성 요소를 설치·전환·갱신합니다.	`rustup update`	러스트 툴체인 관리 범위이며 운영체제 링커와 네이티브 라이브러리는 별도입니다.
`rustc`	러스트 소스를 컴파일하는 실제 컴파일러입니다.	`rustc --version`	현재 선택된 컴파일러의 버전, 커밋 해시, 커밋 날짜가 출력됩니다.
`cargo`	프로젝트 생성, 의존성, 빌드, 실행, 테스트를 한 명령 체계로 묶습니다.	`cargo --version`; `cargo run`	버전이 출력되고 최소 프로젝트가 빌드되어 `Hello, world!`를 출력합니다.
`rustup doc`	설치된 툴체인의 로컬 API 문서를 브라우저에서 엽니다.	표준 라이브러리의 타입과 함수 검색	오프라인에서도 API (Application Programming Interface) 문서를 열 수 있습니다.
`rustup self uninstall`	`rustup`과 설치된 러스트 툴체인을 제거합니다.	환경을 완전히 다시 구성할 때	제거 전 필요한 프로젝트와 셸 설정을 별도로 보존합니다.

`rustup` · 툴체인 관리자

rustup update로 채널과 구성 요소를 갱신합니다. OS 링커와 네이티브 라이브러리는 관리하지 않습니다.

`rustc` · 컴파일러

rustc --version에서 현재 선택된 컴파일러의 버전과 커밋 정보를 확인합니다.

`cargo` · 프로젝트 도구

cargo --version과 최소 cargo run이 모두 성공해야 설치가 끝납니다.

`rustup doc` · 로컬 문서

오프라인에서도 표준 라이브러리 API (Application Programming Interface)를 검색합니다.

`rustup self uninstall` · 제거

rustup과 설치한 러스트 툴체인을 함께 제거하므로 필요한 설정을 먼저 보존합니다.

설치 진단의 최소 순서

rustc --version → cargo --version → cargo run 순서로 보면 PATH, 툴체인, 링커 문제를 나누기 쉽습니다.

업데이트와 제거는 관리 작업

업데이트·문서·제거 명령은 설치 성공 판정과 분리합니다. 첫 실행이 실패하면 먼저 셸, PATH, 운영체제 빌드 도구를 확인합니다.

명령 이름이 비슷해도 책임은 서로 다릅니다. 오류가 난 단계의 소유 도구를 먼저 특정하면 재설치 범위를 줄일 수 있습니다.

로컬 문서

러스트 설치 시 로컬 문서(local documentation)도 같이 설치됩니다.

오프라인 상태로도 이용할 수 있으며, rustup doc 명령어로 여러분의 브라우저에서 열어볼 수 있습니다.

표준 라이브러리에서 제공하는 타입이나 함수 중 이게 무슨 기능을 하는지나 사용하는 법을 모르겠다면 API (Application Programming Interface) 문서에서 모르는 내용을 찾아볼 수도 있겠죠?

설치는 cargo run이 끝날 때 완료된다

인터넷과 셸 고정

rustup 툴체인 설치

운영체제 빌드 도구 확인

같은 셸에서 PATH 확인

컴파일러와 빌드 도구 버전 확인

cargo run으로 완료 판정

명령을 찾지 못함

링커 오류

Windows 설치 범위

이 예의 조건

Rust 설치를 실제 실행까지 확인하는 흐름

설치는 cargo run이 끝날 때 완료된다

인터넷과 셸 고정

rustup 툴체인 설치

운영체제 빌드 도구 확인

같은 셸에서 PATH 확인

컴파일러와 빌드 도구 버전 확인

cargo run으로 완료 판정

명령을 찾지 못함

링커 오류

Windows 설치 범위

이 예의 조건

관계도의 보충 설명

커맨드 라인 표기

rustup 설치 - Linux 및 macOS

rustup 설치 - Windows

트러블 슈팅

업데이트 및 삭제

도구의 책임과 완료 신호를 구분한다

rustup · 툴체인 관리자

rustc · 컴파일러

cargo · 프로젝트 도구

rustup doc · 로컬 문서

rustup self uninstall · 제거

설치 진단의 최소 순서

업데이트와 제거는 관리 작업

로컬 문서

이 페이지 목차

이 페이지 목차

설치는 `cargo run`이 끝날 때 완료된다

`rustup` 툴체인 설치

`cargo run`으로 완료 판정

설치는 `cargo run`이 끝날 때 완료된다

`rustup` 툴체인 설치

`cargo run`으로 완료 판정

`rustup` 설치 - Linux 및 macOS

`rustup` 설치 - Windows

`rustup` · 툴체인 관리자

`rustc` · 컴파일러

`cargo` · 프로젝트 도구

`rustup doc` · 로컬 문서

`rustup self uninstall` · 제거