오늘은 AI 관련하여 최근 Python을 다루는 분들이 많아지는 것 같아, 본격적인 AI 연동 개발 전 Python 개발 환경에 대해 몇가지 다뤄보려고 한다. 그 중 오늘은 로컬 환경 세팅 에 대해 다뤄볼 예정이다.
파이썬 개발의 첫 단추, 로컬 개발 환경 구축을 위한 기본 설정 글이다. "왜 내 컴퓨터에선 안 되지?"라는 질문의 근본 원인인 '의존성 지옥(Dependency Hell)'을 살펴보고, 이를 해결할 수 있는 3가지 핵심 도구 venv, Conda, uv를 비교 분석해보자.
목차
도입: 의존성 지옥이란?
사전 준비: 파이썬 올바르게 설치하기
가상환경, 왜 필수인가?
3대 도구 심층 비교: venv vs Conda vs uv
실전 실습 가이드
IDE 연동: VS Code 설정
프로젝트 관리 베스트 프랙티스
트러블슈팅: 자주 발생하는 에러 해결
FAQ
마무리
이전 글에서 온라인 환경(Google Colab 등)에서 파이썬의 맛을 봤다면, 이제는 진짜 개발을 위해 로컬 설정을 진행해볼 차례다.
많은 입문자가 파이썬을 처음 설치하고 터미널에 pip install pandas를 신나게 입력한다. 처음엔 잘 돌아간다. 나도 그렇게 개발을 많이 했었다. 하지만 1년 뒤, 혹은 프로젝트가 3~4개로 늘어났을 때 반드시 이런 상황을 마주하게 된다.
발생하는 시나리오 예시(의존성 지옥)
상황 1: 버전 충돌 1. Project A(작년 개발)는 Django 2.0을 사용 중 2. Project B(신규 개발)를 위해 Django 4.0을 설치함 3. 갑자기 잘 돌아가던 Project A에서 "ImportError" 에러 발생 4. 원인: 글로벌 환경 하나에 모든 패키지를 덮어씌웠기 때문
상황 2: 협업 문제 1. 동료가 보낸 코드를 받아서 실행 2. "ModuleNotFoundError: No module named 'xxx'" 에러 폭탄 3. 어떤 버전의 라이브러리가 필요한지 아무도 모르는 상황 4. 결국 한동안 삽질...
이것이 바로 개발자들이 말하는 '의존성 지옥(Dependency Hell)'이다. 30년 전 C언어 라이브러리 링크 시절이나 지금이나, 버전 관리는 개발자의 영원한 숙제다. 이 문제를 해결하기 위해 등장한 개념이 바로 '가상환경(Virtual Environment)'이다.
1. 사전 준비: 파이썬 올바르게 설치하기
가상환경을 다루기 전에, 파이썬 자체가 제대로 설치되어 있어야 한다. 의외로 많은 분들이 이 단계에서 실수를 한다.
Microsoft Store 설치 간편하지만 경로 이슈 발생 가능성 있음 일부 패키지와 호환 문제 보고됨
# 설치 확인 (PowerShell 또는 CMD)
python --version
# 출력 예시: Python 3.12.0
# pip 확인
pip --version
# 출력 예시: pip 24.0 from C:\Users\...\site-packages\pip
macOS 파이썬 설치하기
Mac에는 기본적으로 파이썬이 설치되어 있지만, 시스템용이므로 직접 설치하는 것을 권장한다.
✅ 추천: Homebrew 사용 brew install python 버전 관리 용이, 업데이트 간편
python.org 공식 설치 Homebrew 없이 직접 설치 가능 SSL 인증서 수동 설치 필요할 수 있음
💡 python vs python3 Mac/Linux에서는 python이 Python 2를, python3가 Python 3를 가리키는 경우가 있다. 항상 python3 --version으로 확인하고, 필요시 alias를 설정하자. alias python=python3 (~/.zshrc (Mac) 또는 ~/.bashrc (Linux)에 추가)
[Mac 전용] Homebrew Python이 적용 안 될 때
Homebrew로 최신 Python(예: 3.14)을 설치했는데도 python3 --version 실행 시 시스템 기본 Python(예: 3.9)이 나온다면?
ex) 설치전 경로 및 버전 확인 - 3.9.6
- Homebrew로 설치 진행
- 중략. - 설치 후에도 경로 및 버전이 그대로인 케이스
원인: macOS는 /usr/bin/python3 (시스템 Python 3.9)을 기본 제공한다. PATH 환경 변수에서 /usr/bin이 /opt/homebrew/bin보다 앞에 있으면 시스템 Python이 우선 적용된다.
해결 방법:
# 1. 현재 사용 중인 Python 경로 확인
which python3
# 출력이 /usr/bin/python3 이면 문제 상황
# 2. ~/.zshrc 파일 열기 (Mac 기본 쉘)
nano ~/.zshrc
# 또는
open -e ~/.zshrc
# 3. 파일 맨 아래에 아래 내용 추가
export PATH="/opt/homebrew/bin:$PATH"
# 4. 변경사항 적용
source ~/.zshrc
# 또는 터미널 재시작
# 5. 확인
which python3
# 출력: /opt/homebrew/bin/python3 ✅
python3 --version
# 출력: Python 3.14.0 (또는 설치한 버전) ✅
핵심 포인트: • PATH는 왼쪽부터 순서대로 탐색하므로 Homebrew 경로를 앞쪽에 두어야 우선 적용 • export PATH="/opt/homebrew/bin:$PATH"는 기존 PATH 앞에 Homebrew 경로 추가 • Apple Silicon(M1/M2/M3)은 /opt/homebrew, Intel Mac은 /usr/local 사용 • bash 쉘 사용자는 ~/.bashrc 또는 ~/.bash_profile 수정
2. 가상환경, 왜 필수인가?
쉽게 비유하자면 '프로젝트마다 독립된 방(Room)을 만들어 주는 것'이다.
글로벌 설치 (원룸)
모든 프로젝트가 한 공간 공유
A가 바꾼 설정이 B에게 영향
누가 뭘 설치했는지 추적 불가
결국 충돌 → 모두가 불행
✅ 가상환경 (각자의 방)
프로젝트마다 독립된 공간
A방에서 뭘 해도 B방 무관
각 방의 설치 목록 명확
언제든 방을 비우고 새로 시작 가능
가상환경 폴더 구조
my_project/
├── .venv/ # 가상환경 폴더 (이 안에 모든 게 격리됨)
│ │
│ ├── bin/ # 🍎 Mac/Linux 전용
│ │ ├── python # 이 프로젝트 전용 파이썬
│ │ ├── pip # 이 프로젝트 전용 pip
│ │ └── activate # 활성화 스크립트 (source로 실행)
│ │
│ ├── Scripts/ # 🪟 Windows 전용 (Mac/Linux에는 없음)
│ │ ├── python.exe # 이 프로젝트 전용 파이썬
│ │ ├── pip.exe # 이 프로젝트 전용 pip
│ │ └── Activate.ps1 # 활성화 스크립트 (PowerShell)
│ │
│ ├── lib/ # 패키지 저장소
│ │ └── python3.12/
│ │ └── site-packages/ # 설치된 패키지들
│ │ ├── django/
│ │ ├── requests/
│ │ └── ...
│ └── pyvenv.cfg # 가상환경 설정 파일
│
├── main.py # 내 코드
├── requirements.txt # 의존성 목록
└── .gitignore # .venv/ 포함 필수!
가상환경을 사용하면 프로젝트 폴더 안에 .venv라는 폴더가 생기고, 그 안에 해당 프로젝트만을 위한 파이썬 실행 파일과 라이브러리가 격리되어 설치된다. 가상환경을 안 쓴다? 시한폭탄을 안고 개발하는 것과 같다.
3. 가상환경 도구 3파전 : venv vs Conda vs uv
"그래서 뭘 써야 하나요?" 이 질문에 답하기 위해 현업에서 가장 많이 쓰이는 3가지 도구를 비교해보자.
① venv (표준)② Conda (과학/데이터)③ uv (차세대/고성능)
구분
venv
Conda
uv
출시 연도
2012 (Python 3.3)
2012
2024
개발사
Python 공식
Anaconda Inc.
Astral (Ruff 개발사)
구현 언어
Python
Python
Rust
별도 설치
불필요 (내장)
필요 (무거움)
필요 (가벼움)
패키지 설치 속도
보통
느림
10-100배 빠름
파이썬 버전 관리
❌ 불가
✅ 가능
✅ 가능
비-파이썬 패키지
❌ 불가
✅ 가능 (강점)
❌ 불가
Lock 파일
❌ 없음
✅ environment.yml
✅ uv.lock
추천 대상
입문자, 표준 선호자
데이터 사이언스, ML
모든 최신 프로젝트
속도 벤치마크 (실측 데이터)
작업
pip
uv
개선율
가상환경 생성
~2초
~0.1초
20배 ↑
numpy 설치 (캐시 없음)
~25초
~3초
8배 ↑
Django 프로젝트 전체 설치
~90초
~8초
11배 ↑
* Astral 공식 벤치마크 및 커뮤니티 테스트 기반. 실제 환경에 따라 다를 수 있음.
venv 파이썬 표준의 안정성
장점: 아무것도 설치할 필요 없음. 파이썬만 있으면 바로 사용 가능. 가장 널리 알려진 방법이라 문서와 튜토리얼이 풍부함. 단점: 패키지 설치 속도가 느림. 파이썬 버전 자체를 관리할 수 없어 pyenv와 함께 써야 하는 경우가 많음. lock 파일 미지원으로 정확한 버전 재현이 어려움.
Conda 데이터 사이언스의 표준
장점: 파이썬뿐 아니라 C/C++ 기반 라이브러리(CUDA, MKL 등)도 관리 가능. 데이터 사이언스/머신러닝에서 사실상 표준. 파이썬 버전도 관리 가능. 단점: 무겁고 느림. Anaconda 전체 설치 시 수 GB. 일반 웹 개발에는 과한 도구. conda와 pip를 섞어 쓰면 환경이 꼬일 수 있음.
uv 2024년의 게임 체인저
장점: Rust로 작성되어 압도적인 속도. pip의 모든 기능을 대체하면서 훨씬 빠름. lock 파일로 재현 가능한 빌드. pyproject.toml 기반 현대적 프로젝트 관리. 파이썬 버전까지 관리 가능. 단점: 2024년 출시로 아직 새로움. 레거시 프로젝트와의 호환성 검증 필요. 비-파이썬 바이너리 패키지 관리는 Conda가 여전히 우위.
결론: 뭘 선택해야 할까?
• 입문자 / 표준 선호:venv로 시작하자. 구관이 명관. • 데이터 사이언스 / ML:Conda (Miniconda 권장) • 새 프로젝트 / 속도 중시:uv 강력 추천. 나의 경우는 uv로 시작했었기 때문에 계속 uv를 사용하긴 하고 있다.
4. [실습] 내 컴퓨터에 환경 구축하기
1. venv 사용법
파이썬만 깔려있다면 아무것도 더 설치할 필요가 없다.
# 1. 프로젝트 폴더 생성 및 이동
mkdir my_venv_project
cd my_venv_project
# 2. 가상환경 생성
# 형식: python -m venv [가상환경이름]
# 관례적으로 .venv 또는 venv를 사용
python -m venv .venv
# 3. 가상환경 활성화
# [Windows] PowerShell
.venv\Scripts\Activate.ps1
# [Windows] CMD
.venv\Scripts\activate.bat
# [Mac / Linux] bash/zsh
source .venv/bin/activate
# 4. 활성화 확인 (프롬프트 앞에 (.venv)가 보이면 성공이다)
(.venv) PS C:\my_venv_project> # Windows
(.venv) user@mac my_venv_project % # Mac
# 5. 패키지 설치
pip install requests pandas
# 6. 가상환경 비활성화 (작업 끝났을 때)
deactivate
🚫 Windows PowerShell 보안 오류 해결법
Activate.ps1 실행 시 "이 시스템에서 스크립트를 실행할 수 없으므로..." 에러가 뜨는가?
이건 윈도우 보안 정책 때문이다. 관리자 권한으로 PowerShell을 열고 아래 명령어를 입력하자: Set-ExecutionPolicy RemoteSigned -Scope CurrentUser (Y 선택 후 진행)
가상환경 폴더(.venv)는 절대 Git 저장소에 올리면 안 된다. 용량도 클뿐더러, OS마다 파일 구조가 달라서 다른 컴퓨터에서 안 돌아간다.
.gitignore 파일 예시:
# 가상환경
.venv/
venv/
env/
# 파이썬 캐시
__pycache__/
*.pyc
*.pyo
# IDE 설정
.vscode/
.idea/
# 환경 변수 (민감 정보)
.env
2. requirements.txt로 의존성 기록하기 (전통 방식)
내가 어떤 라이브러리를 설치했는지 기록해둬야 동료가(혹은 미래의 내가) 똑같이 설치할 수 있다.
# 현재 설치된 패키지 목록 저장
pip freeze > requirements.txt
# requirements.txt 내용 예시
# django==4.2.0
# requests==2.31.0
# pandas==2.0.3
# 다른 환경에서 똑같이 설치
pip install -r requirements.txt
3. pyproject.toml: 현대적 프로젝트 관리 (권장)
2020년대의 파이썬 프로젝트 표준이다. uv, Poetry 등이 이 형식을 사용한다.
# pyproject.toml 예시
[project]
name = "my-project"
version = "0.1.0"
description = "My awesome project"
requires-python = ">=3.10"
dependencies = [
"requests>=2.28.0",
"pandas>=2.0.0",
]
[project.optional-dependencies]
dev = [
"pytest>=7.0.0",
"ruff>=0.1.0",
]
[tool.uv]
dev-dependencies = [
"pytest>=7.0.0",
]
장점: 프로젝트 메타데이터와 의존성을 한 파일에서 관리. lock 파일과 함께 사용하면 100% 재현 가능한 환경 구축.
7. 트러블슈팅: 자주 발생하는 에러 해결
파이썬 환경 설정에서 자주 마주치는 에러들과 해결법을 정리했다. 에러 메시지로 검색해서 찾아보자.
Error #1
'python' is not recognized as an internal or external command
원인: 파이썬이 시스템 PATH에 등록되지 않음 해결: 파이썬 재설치 시 "Add Python to PATH" 체크. 또는 환경 변수에 수동 추가.
Error #2
이 시스템에서 스크립트를 실행할 수 없으므로
...\Activate.ps1 파일을 로드할 수 없습니다.
원인: Windows PowerShell 실행 정책 제한 해결: 관리자 PowerShell에서 Set-ExecutionPolicy RemoteSigned -Scope CurrentUser 실행
Error #3
ModuleNotFoundError: No module named 'pandas'
원인: 가상환경이 활성화되지 않은 상태에서 실행, 또는 해당 패키지 미설치 해결: 1) 가상환경 활성화 확인 (프롬프트에 (.venv) 표시 확인) 2) pip install pandas 실행
Error #4
zsh: command not found: python
원인: Mac/Linux에서 python3만 설치됨 (python 명령어 없음) 해결:python3 사용하거나, ~/.zshrc (Mac) 또는 ~/.bashrc (Linux)에 alias python=python3 추가
Error #5
ERROR: Could not find a version that satisfies the requirement xxx
원인: 패키지명 오타, 또는 현재 파이썬 버전과 호환되지 않는 패키지 해결: 1) 패키지명 정확히 확인 (PyPI 검색) 2) 파이썬 버전 확인 3) 패키지의 지원 버전 확인
원인: Mac에서 python.org 설치 후 SSL 인증서 미설치 해결: Finder → Applications → Python 3.x 폴더 → "Install Certificates.command" 더블클릭
8. 자주 묻는 질문 (FAQ)
Q: [Mac] Homebrew로 Python을 설치했는데 시스템 Python이 계속 사용돼요
A:which python3 실행 시 /usr/bin/python3가 나온다면 PATH 우선순위 문제다. ~/.zshrc 파일에 export PATH="/opt/homebrew/bin:$PATH"를 추가하고 source ~/.zshrc로 적용하자. 이렇게 하면 Homebrew Python이 시스템 Python보다 우선 적용된다. 위 섹션 2의 노란색 경고 박스를 참고하자.
Q: 가상환경 폴더 이름은 꼭 .venv여야 하나요?
A: 아니다, 원하는 이름을 쓸 수 있다. 하지만 .venv 또는 venv가 업계 관례다. 앞에 점(.)을 붙이면 숨김 폴더가 되어 깔끔하다. VS Code 등 대부분의 IDE가 이 이름을 자동 인식한다.
Q: 프로젝트마다 가상환경을 만들어야 하나요?
A: 그렇다, 강력히 권장한다. 프로젝트마다 필요한 패키지 버전이 다르기 때문이다. "1 프로젝트 = 1 가상환경"을 원칙으로 삼자. 디스크 용량이 걱정된다면 uv는 글로벌 캐시를 사용해 중복을 최소화한다.
Q: venv를 쓰다가 uv로 바꿔도 되나요?
A: 물론이다, 언제든 가능하다. uv는 기존 venv 환경과 호환된다. 기존 .venv 폴더를 그대로 두고 uv pip install로 패키지를 설치할 수 있다. 또는 uv venv로 새로 만들어도 된다.
Q: Conda와 venv/uv를 함께 쓸 수 있나요?
A: 기술적으로는 가능하지만 권장하지 않는다. Conda는 자체적인 환경 관리 체계를 가지고 있어 혼용하면 충돌이 발생할 수 있다. 하나를 선택해서 일관되게 사용하자.
Q: 회사에서는 뭘 쓰나요?
A: 회사마다 다르다. 웹 개발 회사는 venv나 Poetry가 많고, 데이터/ML 팀은 Conda가 많다. 2024년부터는 uv를 채택하는 곳이 빠르게 늘고 있다. 취업을 준비한다면 venv는 기본으로 알아두고, uv도 익혀두면 좋다.
Q: 가상환경을 삭제하려면 어떻게 하나요?
A: 그냥 .venv 폴더를 삭제하면 된다. 특별한 명령어가 필요 없다. 폴더 삭제 후 새로 python -m venv .venv 또는 uv venv로 깨끗하게 시작할 수 있다.
9. 마치며
한눈에 보는 선택 가이드
파이썬 입문자: 내장 venv로 시작. 구관이 명관.
새 프로젝트 시작:uv 강력 추천. 속도와 현대적 기능 모두 잡음.
데이터 사이언스/ML:Miniconda가 여전히 편리.
공통 원칙: "1 프로젝트 = 1 가상환경", .gitignore 필수, 의존성 기록 필수
처음엔 복잡해 보여도, 한 번 손에 익으면 무의식적으로 하게 된다. 다음 포스팅에서는 이렇게 구축한 환경 위에서 실제 프로젝트를 진행해 볼지, 조금더 이론을 살펴볼지 고민 중이다.
