(맥/Mac) Ruby 설치 & 환경 설정 완전 정리 - rbenv로 버전 관리까지

07 April 2026 - 6 mins read time
Tags: macOS Ruby

개요

macOS에는 시스템 Ruby가 기본으로 설치되어 있지만, 버전이 낮고 직접 수정하면 OS에 영향을 줄 수 있습니다.
실무에서는 rbenv 를 사용해 Ruby 버전을 독립적으로 관리하는 것이 표준입니다.
이 글에서는 다음을 다룹니다.
- Homebrew 설치 확인
- rbenv 설치
- Ruby 설치 & 버전 설정
- 전역 환경변수 등록 (.zshrc)
- 설치 검증 & 자주 쓰는 rbenv 명령어

1. 사전 준비 — Homebrew 설치

rbenv는 Homebrew로 설치합니다. 먼저 Homebrew가 있는지 확인합니다.

brew --version

설치가 안 되어 있다면 아래 명령어로 설치합니다.

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

설치 후 Apple Silicon(M1/M2/M3) Mac이라면 Homebrew 경로를 PATH에 추가합니다.

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zshrc
source ~/.zshrc

Intel Mac은 경로가 /usr/local 이므로 별도 설정이 필요 없습니다.

2. 시스템 Ruby 확인

macOS에 기본 설치된 Ruby 경로와 버전을 확인합니다.

which ruby
# /usr/bin/ruby  ← 시스템 Ruby (건드리면 안 됨)

ruby --version
# ruby 2.6.x (macOS 기본 버전, OS마다 다름)

시스템 Ruby(/usr/bin/ruby)는 macOS 내부 도구들이 사용합니다.
gem install 등을 시스템 Ruby에 실행하면 권한 오류가 나거나 OS에 영향을 줄 수 있습니다.
반드시 rbenv로 별도 Ruby를 설치해 사용합니다.

3. rbenv 설치

brew install rbenv ruby-build

rbenv — Ruby 버전 관리 도구
ruby-build — rbenv의 플러그인, 다양한 Ruby 버전을 빌드/설치해줌

설치 확인:

rbenv --version
# rbenv 1.3.x (homebrew)

4. 환경변수 등록 — .zshrc 설정

rbenv가 제대로 동작하려면 쉘 초기화 파일에 설정을 추가해야 합니다.

echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.zshrc
echo 'eval "$(rbenv init - zsh)"' >> ~/.zshrc

변경 사항을 즉시 적용합니다.

source ~/.zshrc

설정이 잘 됐는지 확인합니다.

rbenv doctor

아래와 같이 모두 OK가 나오면 정상입니다.

Checking for `rbenv' in PATH: /opt/homebrew/bin/rbenv
Checking for rbenv shims in PATH: OK
Checking `rbenv install' support: /opt/homebrew/bin/rbenv-install (ruby-build 20241225)
Counting installed Ruby versions: none
  There aren't any Ruby versions installed under `/Users/yourname/.rbenv/versions'.
Auditing installed plugins: OK

5. Ruby 설치

설치 가능한 버전 목록 확인

rbenv install --list

최신 stable 버전들만 보려면:

rbenv install --list-all | grep -v - | grep "^[0-9]"

원하는 버전 설치

rbenv install 3.3.0

설치에 수 분이 걸릴 수 있습니다. 완료 후 확인합니다.

rbenv versions
# * system
#   3.3.0

6. Ruby 버전 설정

전역(Global) 설정 — 모든 터미널에 기본 적용

rbenv global 3.3.0

확인:

rbenv version
# 3.3.0 (set by /Users/yourname/.rbenv/version)

which ruby
# /Users/yourname/.rbenv/shims/ruby  ← 시스템 Ruby가 아님

ruby --version
# ruby 3.3.0

로컬(Local) 설정 — 특정 프로젝트 디렉토리에만 적용

프로젝트 디렉토리에서 실행합니다.

cd ~/my-project
rbenv local 2.7.8

해당 디렉토리에 .ruby-version 파일이 생성됩니다.

cat .ruby-version
# 2.7.8

해당 디렉토리(및 하위)에서는 2.7.8이 자동 적용됩니다.
다른 디렉토리에서는 global 버전이 사용됩니다.

쉘 세션(Shell) 설정 — 현재 터미널 창에만 임시 적용

rbenv shell 3.2.0

터미널을 닫으면 원래 global 버전으로 돌아옵니다.

7. 최종 .zshrc 전체 확인

설정이 올바르게 들어가 있는지 확인합니다.

cat ~/.zshrc

아래 내용이 포함되어 있어야 합니다.

# Homebrew (Apple Silicon)
eval "$(/opt/homebrew/bin/brew shellenv)"

# rbenv
export PATH="$HOME/.rbenv/bin:$PATH"
eval "$(rbenv init - zsh)"

수정 후 반드시 적용합니다.

source ~/.zshrc

8. gem 사용 확인

Ruby 패키지 관리자인 gem이 올바른 경로를 가리키는지 확인합니다.

which gem
# /Users/yourname/.rbenv/shims/gem

gem --version
# 3.5.x

gem environment
# RubyGems Environment:
#   - RUBYGEMS VERSION: 3.5.x
#   - RUBY VERSION: 3.3.0
#   - INSTALLATION DIRECTORY: /Users/yourname/.rbenv/versions/3.3.0/lib/ruby/gems/3.3.0

INSTALLATION DIRECTORY가 .rbenv 경로를 가리키면 정상입니다.

Bundler 설치 (Jekyll, Rails 등 대부분의 프로젝트에서 필요):

gem install bundler

9. Jekyll 블로그 연동 예시 (GitHub Pages)

Jekyll 블로그를 로컬에서 실행할 때도 rbenv로 Ruby를 관리합니다.

# 프로젝트 디렉토리로 이동
cd ~/my-blog

# 로컬 Ruby 버전 설정 (Jekyll 권장 버전)
rbenv local 3.1.6

# 의존성 설치
bundle install

# 로컬 서버 실행
bundle exec jekyll serve

10. 자주 쓰는 rbenv 명령어 정리

명령어	설명
`rbenv install --list`	설치 가능한 최신 stable 버전 목록
`rbenv install --list-all`	설치 가능한 모든 버전 목록
`rbenv install 3.3.0`	특정 버전 설치
`rbenv uninstall 3.3.0`	특정 버전 제거
`rbenv versions`	설치된 모든 버전 목록
`rbenv version`	현재 적용 중인 버전 확인
`rbenv global 3.3.0`	전역 버전 설정
`rbenv local 3.1.6`	현재 디렉토리 버전 설정
`rbenv shell 3.2.0`	현재 쉘 세션에만 버전 설정
`rbenv rehash`	shim 갱신 (새 gem 설치 후 명령어 인식 안 될 때)
`rbenv doctor`	rbenv 설정 진단
`rbenv which ruby`	현재 ruby 실행 파일 실제 경로 확인

11. 자주 겪는 문제

ruby 명령이 여전히 시스템 Ruby를 가리킬 때

# 현재 which 결과 확인
which ruby
# /usr/bin/ruby  ← 아직 시스템 Ruby

# .zshrc에 rbenv init이 제대로 들어가 있는지 확인
grep rbenv ~/.zshrc

# 재적용
source ~/.zshrc

rbenv install 시 빌드 오류

Xcode Command Line Tools가 없는 경우 발생합니다.

xcode-select --install

gem install 시 권한 오류

/usr/local이나 /usr/bin에 설치하려는 경우입니다. rbenv의 Ruby가 아닌 시스템 Ruby를 사용 중일 가능성이 높습니다. 6번 항목을 다시 확인하세요.

터미널 재시작 후 버전이 초기화됨

.zshrc가 아닌 .bash_profile이나 .bashrc에 설정했을 가능성이 있습니다. macOS Catalina 이후 기본 쉘은 zsh이므로 ~/.zshrc에 설정해야 합니다.

echo $SHELL
# /bin/zsh  ← zsh라면 .zshrc에 설정

정리

brew install rbenv ruby-build — rbenv 설치
~/.zshrc에 eval "$(rbenv init - zsh)" 추가
source ~/.zshrc 적용
rbenv install 3.3.0 — 원하는 버전 설치
rbenv global 3.3.0 — 전역 버전 지정
ruby --version 으로 최종 확인

시스템 Ruby는 절대 건드리지 말고, rbenv로 설치한 Ruby만 사용하는 것이 핵심입니다.