가상환경 세팅 방법

가상환경 세팅 방법 (uv)

한마디 요약

uv venv로 프로젝트 폴더 안에 .venv라는 미니 파이썬 런타임을 짓고, activate로 그 안에 “들어간 뒤” uv pip install로 도구를 채워 넣는 흐름임.

가상환경이 왜 필요한가

가상환경(virtual environment, 프로젝트별로 격리된 파이썬 인터프리터와 패키지 설치 공간)을 안 쓰면, 모든 프로젝트가 전역 파이썬을 공유함. 한 프로젝트에서 numpy==1.24를 요구하고 다른 프로젝트에서 numpy==2.0을 쓰면 서로 덮어쓰면서 깨짐.

일상 비유: 전역 파이썬 = 공용 공구함, 가상환경 = 프로젝트 전용 연구실. 공구를 연구실 안에만 두면 옆 연구실 작업에 영향을 주지 않음.

처음설치

계획 (의사코드)

1. uv 존재 여부 확인함
2. 프로젝트 폴더 준비함
3. uv venv .venv 로 가상환경 생성함
4. .venv\Scripts\activate 로 활성화함
5. uv pip install <패키지> 로 필요한 모듈 설치함
6. uv pip list 로 설치 확인함
7. 필요 시 ipykernel 등록함

1단계: uv 설치 확인

uv --version

버전이 안 나오면 설치부터 진행함:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

2단계: 프로젝트 폴더 준비

mkdir my_project
cd my_project

3단계: 가상환경 생성

새 미니 연구실을 짓는 단계임.

uv venv .venv

• 기본 폴더명 .venv는 생략 가능 (uv venv 만 쳐도 .venv가 생김)
• 다른 이름이 필요하면 uv venv my_env 처럼 지정

특정 파이썬 버전이 필요하면:

uv venv .venv --python 3.11

버전 자동 다운로드

공식 문서에 따르면 시스템에 해당 파이썬 버전이 없으면 uv가 자동으로 다운로드해서 설치해 줌. 별도 pyenv 설치가 필요 없음.

직접 확인: .venv\Scripts\python.exe 파일이 생겼는지 확인.

dir .venv\Scripts\python.exe

4단계: 가상환경 활성화

연구실 문을 열고 들어가는 과정임. 활성화하면 이후 python, pip 명령이 .venv 안의 실행 파일을 가리키게 됨.

셸/OS	활성화 명령
Windows CMD	.venv\Scripts\activate.bat
Windows PowerShell	.venv\Scripts\Activate.ps1
macOS/Linux (bash/zsh)	source .venv/bin/activate
Fish	source .venv/bin/activate.fish

성공 표시: 프롬프트 앞에 (.venv) 같은 프리픽스가 붙음.

직접 확인: 활성화 후 where python (Windows) 또는 which python (Unix) 실행 시, .venv\Scripts\python.exe 경로가 찍혀야 함.

5단계: 패키지 설치

연구실에 필요한 도구(패키지)를 채워 넣음.

uv pip install numpy pandas

이미 의존성 선언 파일이 있다면 다음 중 하나를 씀:

# pyproject.toml 기반 (editable install 포함)
uv pip install -e .
 
# requirements.txt 기반
uv pip install -r requirements.txt
 
# uv 네이티브 (pyproject.toml + uv.lock)
uv sync

자세한 동기화 차이: UV_SYNC_GUIDE

6단계: 설치 확인

uv pip list

출력 예시:

Package    Version
---------- -------
numpy      2.1.3
pandas     2.2.3
...

7단계: 주피터 커널 등록 (필요 시)

노트북에서 이 가상환경을 커널로 선택할 수 있게 하는 단계임.

uv pip install ipykernel
python -m ipykernel install --user --name "my-env" --display-name "My Env"

• --name: 내부 식별자 (영문/숫자/하이픈만 권장)
• --display-name: 주피터 UI 커널 목록에 보이는 이름

직접 확인:

jupyter kernelspec list

에 my-env 항목이 찍혀야 함.

빠른 참조: 전체 흐름

cd my_project
uv venv .venv --python 3.12
.venv\Scripts\activate.bat
uv pip install -e .
uv pip list

왜 uv인가 (대안 대비)

도구	속도	가상환경 생성	패키지 설치	잠금 파일
python -m venv + pip	느림	가능	가능	없음
virtualenv + pip	중간	가능	가능	없음
poetry	느림	가능	가능	poetry.lock
uv	매우 빠름	가능	가능	uv.lock

uv의 속도 비결: Rust 구현 + 병렬 다운로드 + 캐시 하드링크(동일 패키지를 여러 프로젝트에서 쓸 때 디스크 중복을 피함). 단, 클라우드 동기화 폴더에서는 하드링크가 막힘: 가상환경 재설치 uv의 UV_LINK_MODE=copy 항목 참고.

재설치 (요약판)

자세한 내용은 가상환경 재설치 uv 노트 참고. 핵심 흐름만:

1단계: 기존 가상환경 철거

셸	명령
CMD	rmdir /s /q .venv
PowerShell	Remove-Item -Recurse -Force .venv

2단계: 새 가상환경 생성

uv venv .venv

특정 버전:

uv venv .venv --python 3.11

3단계: 활성화 및 패키지 재설치

.venv\Scripts\activate.bat
uv pip install -e .

4단계: 확인 및 커널 등록 (필요 시)

uv pip list
python -m ipykernel install --user --name "새환경이름" --display-name "보기 쉬운 이름"

용어 풀이

용어	풀이
가상환경	프로젝트별로 격리된 파이썬 런타임 + site-packages 공간
deactivate	가상환경에서 나와 전역 환경으로 복귀하는 명령
uv venv	가상환경을 생성하는 uv 하위 명령
uv pip install	활성화된 가상환경의 site-packages 에 패키지를 설치
site-packages	가상환경의 실제 패키지 저장 폴더 (.venv\Lib\site-packages)

포함 관계

• 파이썬 설치본 (전역 인터프리터 + 전역 site-packages)
  • 가상환경 .venv
    • .venv\Scripts\python.exe (전용 인터프리터, 전역 파일을 심볼릭하게 참조)
    • .venv\Scripts\activate (활성화 스크립트)
    • .venv\Lib\site-packages (전용 패키지 저장소)
  • 다른 프로젝트의 .venv (서로 완전 격리)

관련 노트

• UV_SYNC_GUIDE (설치 이후 동기화 관리)
• 가상환경 재설치 uv (완전 철거 후 재생성)
• IDE 가 가상환경의 파이썬 인식 못할때 (에디터가 .venv를 못 잡을 때)
• 운영체제와 상관없는 경로설정 (가상환경 안에서 파일 경로 다루기)