MacOS Python3 개발을 위한 Pyenv와 Autoenv 구성 방법

파이썬은 프로젝트마다 요구하는 버전이 다르다. 오래된 사내 도구는 3.9 에 묶여 있고, 새로 시작하는 프로젝트는 3.13 을 쓰고, 어떤 라이브러리는 특정 버전 이상에서만 설치된다. 맥에 기본으로 깔린 python3 하나에 모든 라이브러리를 pip install 하다 보면 결국 한 프로젝트를 고치려고 다른 프로젝트를 망가뜨리는 일이 생긴다.

파이썬 버전과 라이브러리를 프로젝트별로 격리하는 환경은 이제 거의 필수다. 이 글은 macOS + zsh 에서 pyenv, pyenv-virtualenv, autoenv 를 함께 써서 프로젝트 폴더에 들어가기만 하면 맞는 파이썬과 환경 변수가 준비되도록 만드는 방법을 정리한 것이다. macOS 26 · pyenv 2.7.3 · pyenv-virtualenv 1.4.1 · autoenv 0.4.0 에서 확인했고, 직접 시험해 보고 알게 된 내용도 함께 적었다.

목차
  1. pyenv·pyenv-virtualenv·autoenv 가 각각 하는 일
  2. macOS에 설치하기
  3. zsh 설정: pyenv init 과 autoenv 연결
  4. 파이썬 설치와 가상환경: global·local·shell
  5. global: 기본으로 쓸 가상환경
  6. local: 프로젝트 폴더 전용 가상환경
  7. shell: 지금 터미널에서만 잠깐 바꾸기
  8. pip install 에서 zsh: no matches found 가 날 때
  9. autoenv로 폴더에 들어갈 때 프로젝트 설정 불러오기
  10. 처음 실행할 때 허가를 묻는다
  11. .env 에 PYENV_VERSION 을 넣었을 때의 문제
  12. 요즘은 uv가 더 좋더라
  13. .gitignore 에 넣을 파일

pyenv·pyenv-virtualenv·autoenv 가 각각 하는 일

세 도구가 하는 일이 서로 달라서, 역할을 먼저 구분해 두면 설정할 때 덜 헷갈린다.

  • pyenv: 여러 파이썬 버전을 설치하고, 지금 폴더에서 어떤 버전을 쓸지 고른다. 소스를 내려받아 빌드하는 복잡한 과정을 pyenv install 한 번으로 끝내 준다.
  • pyenv-virtualenv: pyenv 플러그인이다. 설치한 파이썬 버전을 바탕으로 가상환경을 만들고, 그 가상환경을 pyenv 버전처럼 이름으로 고를 수 있게 해 준다. 가상환경마다 pip 로 설치한 라이브러리가 따로 저장된다.
  • autoenv: pyenv 와 직접 관계는 없다. cd 로 폴더에 들어갈 때 그 폴더의 .env 스크립트를 실행해 준다. 프로젝트 환경 변수나 안내 문구를 자동으로 띄우는 데 쓴다.

pyenv 가 버전을 고르는 방식도 알아 두면 좋다. pyenv init 을 셸에 넣으면 ~/.pyenv/shims 폴더가 PATH 맨 앞에 붙는다. 이후 python·pip 를 치면 실제 프로그램 대신 이 shim 이 먼저 실행되고, shim 이 아래 순서로 버전을 찾아 그 버전의 프로그램을 대신 실행한다.

우선순위버전을 정하는 곳만드는 명령
1PYENV_VERSION 환경 변수pyenv shell 이름
2현재 폴더의 .python-version, 없으면 상위 폴더를 차례로 올라가며 처음 찾은 파일pyenv local 이름
3~/.pyenv/version (전역)pyenv global 이름

상위 폴더까지 찾아 올라간다는 점이 중요하다. 프로젝트 맨 위 폴더에 .python-version 하나만 두면 그 아래 하위 폴더 어디에서 실행해도 같은 버전이 선택된다.

macOS에 설치하기

Xcode Command Line Tools 와 Homebrew 가 먼저 있어야 한다. pyenv 는 파이썬을 소스에서 빌드하므로, pyenv 위키의 “Suggested build environment” 에 있는 빌드용 라이브러리도 함께 설치해 둔다. 이게 빠지면 설치는 끝났는데 ssl·sqlite3·tkinter 같은 모듈이 빠진 파이썬이 만들어질 수 있다.

## Xcode Command Line Tools
> xcode-select --install

## Homebrew (이미 있으면 건너뛴다)
> /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

## 파이썬 빌드에 필요한 라이브러리 (pyenv 위키의 macOS 항목)
> brew install openssl@3 openssl readline sqlite3 xz tcl-tk@8 libb2 zstd zlib pkgconfig

## pyenv 와 플러그인, autoenv
> brew install pyenv pyenv-virtualenv autoenv
Code language: Bash (bash)

pyenv 가 파이썬을 설치할 때 쓰는 python-build 는 pyenv 안에 들어 있어서 따로 설치하지 않는다. Homebrew 에 있는 python-build 패키지는 PyPA 의 build(PEP 517 빌드 도구)로, 이름만 같고 pyenv 와는 상관없는 프로그램이다. 설치가 끝났으면 버전으로 확인한다.

> pyenv --version
pyenv 2.7.3

## pyenv 에 들어 있는 python-build
> pyenv install --version
python-build 2.7.3
Code language: Bash (bash)

zsh 설정: pyenv init 과 autoenv 연결

pyenv README 는 ~/.zshrc 에 아래 세 줄을 넣으라고 안내한다. pyenv init --path 한 줄만 넣는 설정도 있는데, 이것은 shim 만 PATH 에 붙이고 셸 함수는 만들지 않는다. 버전 선택은 되지만 셸 함수가 처리하는 pyenv shell 은 동작하지 않으니 세 줄을 다 넣는다.

## pyenv (pyenv README 의 zsh 설정)
> echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zshrc
> echo '[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrc
> echo 'eval "$(pyenv init - zsh)"' >> ~/.zshrc

## pyenv-virtualenv 자동 활성화 (선택)
> echo 'eval "$(pyenv virtualenv-init -)"' >> ~/.zshrc

## autoenv
> echo 'source "$(brew --prefix autoenv)/activate.sh"' >> ~/.zshrc
Code language: Bash (bash)

pyenv init 을 인자 없이 실행하면 어디에 무엇을 넣으라는 안내가 나온다. ~/.zshrc 는 대화형 셸에서만 읽히므로, 터미널에서 쓰는 용도라면 여기에 넣는 것으로 충분하다. 대화형이 아닌 로그인 셸에서 실행되는 스크립트나 도구에서도 pyenv 가 필요하면 ~/.zprofile 에도 같은 줄을 넣는다.

> pyenv init
# Load pyenv automatically by appending
# the following to
# ~/.zprofile (for login shells)
# and ~/.zshrc (for interactive shells) :

export PYENV_ROOT="$HOME/.pyenv"
[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init - zsh)"

# Restart your shell for the changes to take effect.
Code language: Bash (bash)

autoenv 가 읽는 파일 이름은 기본값이 .env 이고, 이 글의 예시도 .env 로 쓴다. 그런데 .env 는 python-dotenv 나 Docker Compose 가 KEY=VALUE 형식으로 읽는 파일 이름이기도 해서, 셸 명령을 담는 autoenv 파일과 섞이면 서로 방해가 된다. 그런 도구를 쓰는 프로젝트라면 activate.sh 줄보다 앞에 export AUTOENV_ENV_FILENAME=".autoenv" 를 넣어 autoenv 파일 이름을 바꾸고, 아래 예시의 .env 도 .autoenv 로 바꿔 읽는다.

파이썬 설치와 가상환경: global·local·shell

pyenv 명령은 버전 앞자리만 줘도 된다. pyenv install 3.13 은 pyenv 가 알고 있는 3.13 계열 최신 버전을 설치한다. 무엇이 설치될지는 pyenv latest -k 로 미리 볼 수 있다. pyenv 가 아는 버전 목록은 pyenv 업데이트와 함께 늘어나므로, 새 파이썬이 안 보이면 brew upgrade pyenv 부터 한다.

## 설치 가능한 3.13 버전 목록
> pyenv install -l | grep ' 3\.13'

## 3.13 계열에서 pyenv 가 아는 최신 버전
> pyenv latest -k 3.13
3.13.14

## 앞자리만 주면 위 버전을 설치한다
> pyenv install 3.13
Code language: Bash (bash)

아래 출력은 3.11.3 으로 진행했을 때의 것이다. 버전 숫자만 다를 뿐 명령과 출력 형태는 같다. /Users/name 은 자기 홈 폴더로 바꿔 읽으면 된다.

global: 기본으로 쓸 가상환경

시스템 파이썬에 직접 라이브러리를 설치하지 않도록, 설치한 버전을 바탕으로 base 가상환경을 만들어 전역으로 지정한다.

> pyenv versions
* system
  3.11.3

## 3.11.3 을 바탕으로 base 가상환경을 만든다
> pyenv virtualenv 3.11.3 base

> pyenv versions
* system
  3.11.3
  3.11.3/envs/base
  base

## base 를 전역으로 지정한다 (~/.pyenv/version 에 저장된다)
> pyenv global base

> pyenv versions
  system
  3.11.3
  3.11.3/envs/base
* base --> /Users/name/.pyenv/versions/3.11.3/envs/base (set by /Users/name/.pyenv/version)
Code language: Bash (bash)

가상환경은 ~/.pyenv/versions/3.11.3/envs/base 에 만들어지고, base 라는 짧은 이름이 그 폴더를 가리킨다. 목록은 pyenv virtualenvs, 삭제는 pyenv virtualenv-delete base 나 pyenv uninstall base 로 한다.

local: 프로젝트 폴더 전용 가상환경

프로젝트 폴더에서 pyenv local 을 실행하면 .python-version 파일이 생기고, 그 폴더와 하위 폴더에서는 이 가상환경이 선택된다.

> mkdir ~/projectA && cd ~/projectA

## 아직 local 설정이 없어 전역 base 가 선택된다
> pyenv version
base (set by /Users/name/.pyenv/version)

## projectA 가상환경을 만들고 이 폴더에 지정한다
> pyenv virtualenv 3.11.3 projectA
> pyenv local projectA

> cat .python-version
projectA

> pyenv version
projectA (set by /Users/name/projectA/.python-version)
Code language: Bash (bash)

이 상태에서는 activate 를 하지 않아도 python·pip 가 projectA 가상환경의 것으로 실행된다. shim 이 .python-version 을 보고 고르기 때문이다. 셸 설정에 pyenv virtualenv-init 까지 넣었다면 폴더에 들어갈 때 가상환경이 정식으로 활성화되고(VIRTUAL_ENV 가 설정된다), 폴더를 나가면 비활성화된다.

shell: 지금 터미널에서만 잠깐 바꾸기

pyenv shell 은 PYENV_VERSION 환경 변수를 설정한다. 우선순위가 가장 높아서 .python-version 이 있는 폴더에서도 이 값이 이기고, 터미널을 닫거나 unset PYENV_VERSION 할 때까지 유지된다.

> cd ~/projectA
> pyenv version
projectA (set by /Users/name/projectA/.python-version)

## projectA 폴더 안이지만 base 로 잠깐 실행해야 할 때
> pyenv shell base
> pyenv version
base (set by PYENV_VERSION environment variable)

## 해제하면 다시 .python-version 을 따른다
> unset PYENV_VERSION
> pyenv version
projectA (set by /Users/name/projectA/.python-version)
Code language: Bash (bash)

set by 뒤에 버전을 정한 곳이 나오므로, 예상과 다른 파이썬이 실행되면 pyenv version 부터 보면 원인을 바로 찾을 수 있다.

pip install 에서 zsh: no matches found 가 날 때

가상환경에 라이브러리를 설치할 때 zsh 에서 생기는 오류가 있다. pip install uvicorn[standard] 처럼 대괄호로 추가 기능(extras)을 지정해 설치하면 zsh: no matches found: uvicorn[standard] 오류가 난다. zsh 가 대괄호를 파일 이름 패턴(glob)으로 해석하고, 맞는 파일이 없으니 명령 실행 전에 멈추는 것이다.

> pip install uvicorn[standard]
zsh: no matches found: uvicorn[standard]

## 따옴표로 감싸면 패턴으로 해석하지 않는다
> pip install 'uvicorn[standard]'

## 매번 따옴표를 치기 싫다면 pip 만 noglob 으로 감싼다
> echo 'alias pip="noglob pip"' >> ~/.zshrc
> echo 'alias pip3="noglob pip3"' >> ~/.zshrc
Code language: Bash (bash)

python·python3 까지 noglob 별칭으로 감싸면 python merge.py data/*.csv 처럼 일부러 패턴을 쓰는 명령에서도 * 가 펼쳐지지 않는다. 대괄호 문제가 생기는 건 사실상 pip install 뿐이라 pip 만 감싼다.

autoenv로 폴더에 들어갈 때 프로젝트 설정 불러오기

pyenv 만으로 파이썬 버전은 자동으로 바뀌지만, 프로젝트마다 필요한 환경 변수(데이터 폴더, API 엔드포인트, 디버그 옵션 등)는 따로 챙겨야 한다. autoenv 는 이 부분을 맡는다. 동작 방식은 이렇다.

  • activate.sh 를 불러오면 쉘의 cd 가 autoenv 함수로 바뀐다.
  • cd 할 때마다 현재 폴더부터 상위 폴더까지 .env 를 찾고, 위쪽 폴더의 파일부터 차례로 실행한다. 프로젝트의 하위 폴더로 cd 해도 프로젝트 맨 위의 .env 가 다시 실행된다.
  • 파일은 지금 셸 안에서 source 되고, 그동안 set -a 가 켜져 있어서 export 를 쓰지 않은 변수도 환경 변수로 내보내진다.

처음 실행할 때 허가를 묻는다

새 파일이거나 내용이 바뀐 파일이면 autoenv 가 내용을 보여 주고 실행해도 되는지 묻는다. 허가한 파일은 파일 위치와 해시가 ~/.local/state/autoenv/authorized_list 에 기록되고(이전 버전의 ~/.autoenv_authorized 가 있으면 그 파일을 계속 쓴다), 내용이 한 글자라도 바뀌면 다시 묻는다. 시험용 폴더에서 실제로 실행해 본 화면이다.

> cd projectA
[autoenv] New or modified env file detected
--- Contents of ".env" ----------------------------------
export MY_STORE_DIR="/tmp/devel_dir"
echo "# projectA 설정을 불러왔다"
---------------------------------------------------------
[autoenv] Authorize this file? (y/n/d) y
# projectA 설정을 불러왔다

> echo $MY_STORE_DIR
/tmp/devel_dir
Code language: Bash (bash)

AUTOENV_ASSUME_YES 는 이 질문을 건너뛰고 처음 보는 파일도 바로 실행하게 만든다. 편하긴 하지만, 남의 저장소를 클론해서 cd 하는 순간 그 저장소의 .env 에 적힌 명령이 내 셸에서 그대로 실행된다는 뜻이다. 한 번 y 를 누르는 수고가 그 위험보다 훨씬 싸서 켜지 않는다.

.env 에 PYENV_VERSION 을 넣었을 때의 문제

위와 같이 폴더에 진입했을 때 autoenv로 잘 동작한다. 문제는 폴더를 벗어났을 때다. autoenv 는 .env 를 지금 쉘에서 실행하므로, 거기서 내보낸 PYENV_VERSION 은 프로젝트 폴더를 벗어난 뒤에도 터미널 환경에 남아 있게 된다. PYENV_VERSION 은 우선순위 1번이라, 그 뒤로 다른 프로젝트 폴더에 들어가도 그 폴더의 .python-version 대신 projectA 가 계속 선택된 상태가 된다.

## 시험용 .env : export PYENV_VERSION=projectA 와 echo "[.env 실행] $PWD"
> cd ~/projectA
[.env 실행] /Users/name/projectA
> echo $PYENV_VERSION
projectA

## 하위 폴더로 이동해도 .env 가 다시 실행된다
> cd src
[.env 실행] /Users/name/projectA/src

## 프로젝트를 떠나도 값이 남아 있다
> cd ~/other
> echo $PYENV_VERSION
projectA
Code language: Bash (bash)

버전 선택은 .python-version 에 맡기고, .env 에는 파이썬 버전과 관계없는 프로젝트 설정만 두는 것이 가장 단순하다. pyenv local 은 한 번 실행하면 파일이 남으니 cd 할 때마다 다시 실행할 필요도 없다.

## ~/projectA/.env : 파이썬 버전은 .python-version 에 맡긴다
export MY_STORE_DIR="/tmp/devel_dir"
export APP_DEBUG=1
echo "# $(pyenv version)"
Code language: Bash (bash)

근본적인 문제를 해결하기 위해서는 폴더를 벗어날 때 변수를 정리하도록 AUTOENV_ENABLE_LEAVE 를 켜고 .env.leave 를 만들어 둬야 한다. 폴더를 벗어날 때 이 파일이 실행된다. .env.leave 에 unset 을 넣으면 폴더를 벗어날 때 터미널 변수를 비워놓을 수 있다.

## ~/.zshrc (activate.sh 보다 앞에 설정)
export AUTOENV_ENABLE_LEAVE=1

## ~/projectA/.env.leave
unset MY_STORE_DIR APP_DEBUG
Code language: Bash (bash)

요즘은 uv가 더 좋더라

파이썬 설치와 가상환경, 패키지 설치를 하나로 묶어 처리하는 uv 를 사용하는 더 간단한 방법이 있다. pyenv 와 비교해 보면 이렇다.

항목pyenv + pyenv-virtualenvuv
파이썬 설치소스를 받아 이 Mac 에서 빌드 (pyenv install)python-build-standalone 의 미리 빌드된 파일을 내려받음 (uv python install)
버전 지정 파일.python-version (현재·상위 폴더).python-version (현재·상위 폴더), uv python pin 으로 생성
가상환경 위치~/.pyenv/versions/버전/envs/이름프로젝트 폴더의 .venv (uv venv 기본값)
서로의 관계–pyenv 로 설치한 파이썬도 찾아서 쓰지만 “시스템 파이썬”으로 취급

양쪽 구성에서 .python-version 을 읽는다는 점은 알아 둘 만하다. 버전 숫자(3.13)만 적어 두면 어느 쪽을 쓰든 같은 버전을 고르지만, projectA 처럼 pyenv 가상환경 이름을 적어 두면 uv 는 Ignoring unsupported Python request `projectA` 경고를 내고 그 파일을 무시한 채 다른 파이썬을 고른다. 이미 pyenv 로 잘 돌아가는 프로젝트라면 굳이 변경할 필요는 없고, 새 프로젝트를 시작한다면 uv 로 시작하는 것이 좋을 것 같다.

.gitignore 에 넣을 파일

.python-version 에 projectA 같은 가상환경 이름을 사용하면 내 Mac 에서만 의미가 있게 된다. autoenv 의 .autoenv 는 개인 설정으로 사용하는 편이다. 저장소에 올라가면 다른 사람 환경에서 오류를 내거나, 앞에서 본 것처럼 남의 셸에서 실행될 수 있으므로, git 으로 관리하는 프로젝트라면 .gitignore 에 넣어 두는 게 좋다. 팀이 파이썬 버전 숫자만 공유하려는 경우 .python-version 을 커밋하기도 하므로, 이때는 가상환경 이름 대신 Python 버전만 커밋되는 게 맞다.

## .gitignore
.python-version
.env
.env.leave
.autoenv
.venv/
Code language: Bash (bash)

버전 선택은 .python-version 에, 프로젝트 공통 환경 변수는 .env 에 두고 프로젝트 개인 환경 구성은 .autoenv 에 두는 것으로 프로젝트 환경 구성을 수월하게 통일시킬 수 있다. autoenv 로 폴더마다 GitHub 계정을 바꾸는 방법은 맥북 한 대로 GitHub 여러 계정 쓰기 글에 정리해 두었다.

참고 자료

댓글 남기기

이메일 주소는 공개되지 않습니다. 필수 필드는 *로 표시됩니다

댓글은 운영자가 확인한 뒤 공개됩니다. 이메일은 공개되지 않습니다.

공유하기

MacOS Python3 개발을 위한 Pyenv와 Autoenv 구성 방법

axgo.byitx.com

LINE텔레그램밴드XFacebook