Python 환경 설정

venv — 파이썬 표준 가상환경 도구

가상환경(Virtual Environment)은 파이썬에 기본 내장되어 있는 가상환경 도구로, 프로젝트마다 독립적인 파이썬 환경을 만들어주는 공간이다.
즉, 다른 프로젝트와 패키지 충돌 없이 각자 필요한 라이브러리를 따로 설치하고 쓸 수 있게 해준다.

# 새 가상환경 만들기
python -m venv myenv

# 가상환경 활성화
# (Windows)
myenv\Scripts\activate
# (Mac/Linux)
source myenv/bin/activate

# 패키지 설치
pip install requests

# 가상환경 종료
deactivate

이렇게 하면 myenv 폴더 안에 독립적인 Python + pip 환경이 만들어지고, 여기서 설치한 라이브러리는 다른 프로젝트에 영향을 주지 않는다.

uv — 초고속 패키지/환경 관리 도구

uv는 파이썬용 차세대 패키지 관리 툴로, venv + pip + virtualenv + pip-tools 기능을 한 번에 빠르게 처리할 수 있다.

# uv 설치
pip install uv

# 새로운 가상환경 생성 및 진입
uv venv myenv
source myenv/bin/activate

# 또는 패키지 설치와 동시에 자동 가상환경 생성
uv pip install requests

# 종속성(의존성) 자동 관리
uv lock

이렇게 하면 venv처럼 환경을 만들지만, 속도는 훨씬 빠르고 패키지 관리도 더 깔끔하게 된다.

venv와 uv의 차이점

구분	venv	uv
설치 필요	❌ (기본 내장)	⭕ (별도 설치)
속도	보통	⚡ 매우 빠름
의존성 관리	수동 (`requirements.txt`)	자동 (`uv.lock`)
사용 편의성	단순	강력하고 직관적
패키지 캐시	❌ 없음	⭕ 있음 (재설치 시 빠름)

uv를 활용한 python 버전 관리

uv는 단순히 패키지 관리자(pip 대체)나 가상환경 도구(venv 대체)일 뿐만 아니라 Python 버전까지 자동으로 관리할 수 있는 통합 도구로, 내부적으로 Python 설치/관리 기능을 포함하고 있어서 프로젝트마다 다른 파이썬 버전을 자동으로 설치하고 사용할 수 있다.

가상환경 생성 시 버전 지정

해당 버전이 설치되어 있지 않다면, uv가 자동으로 다운로드하고 설치하기 때문에 별도의 pyenv나 python.org에서 설치할 필요가 없다.

# Python 3.10 버전으로 가상환경 생성
uv venv --python 3.10

# Python 3.12 버전으로 생성
uv venv --python 3.12

프로젝트 설정 파일(pyproject.toml)

uv는 pyproject.toml 안에 Python 버전 요구사항을 명시할 수 있어, $ uv sync명령으로 실행 시 uv가 자동으로 적합한 Python 버전을 찾아 설치하고 사용한다.

[project]
name = "my-app"
version = "0.1.0"
requires-python = ">=3.11,<3.13"

버전 확인 및 관리 명령어

명령어	설명
`uv python list`	설치된 파이썬 버전 목록 보기
`uv python install 3.12`	특정 파이썬 버전 설치
`uv python pin 3.11`	현재 프로젝트에 특정 버전 고정
`uv python which`	현재 사용하는 파이썬 실행 파일 경로 표시

기본 구조 (uv venv로 가상환경 생성 시)

my_project/
│
├── .venv/                ← 가상환경 폴더 (python, pip, site-packages 등)
│   ├── bin/              ← 실행 파일들 (python, uv, pip 등)
│   ├── include/
│   ├── lib/
│   └── pyvenv.cfg
│
├── pyproject.toml        ← (선택) 프로젝트 설정 파일 (의존성, Python 버전 등)
├── uv.lock               ← (자동 생성) 패키지 버전 고정 파일
├── .python-version       ← 현재 프로젝트의 Python 버전 (예: "3.11.8")
├── requirements.txt      ← (선택) 기존 pip 방식 호환용
└── main.py               ← (예시) 소스 코드 파일

uv 기반 Python 프로젝트 템플릿 자동 생성 스크립트

setup_uv_project.sh 스크립트를 작성하면 아래와 같은 폴더 구조를 가진 프로젝트가 생성된다.

프로젝트 폴더 생성
.venv 가상환경 생성 (uv 사용)
pyproject.toml 자동 생성 (프로젝트 이름, 버전, Python 버전 포함)
main.py, README.md, .gitignore 기본 파일 생성

“어디서든 쉽게 실행할 수 있게” 저장하는 게 핵심으로, 어떤 용도로 쓸지에 따라 두 가지 방법으로 저장해서 사용할 수 있다.

1. 특정 프로젝트에서만 사용할 경우

프로젝트별로 스크립트를 커스터마이징이 가능하며, 다른 사람에게 폴더째로 공유하기 쉬운 장점이 있다.

my_workspace/
└── setup_uv_project.sh     ← 여기에 저장

2. 어디서나 명령어처럼 쓰고 싶을 경우

전역 실행용으로 PATH에 등록된 폴더에 저장하는 방식으로, 개발자들이 자주 쓰는 “한 줄 명령형” 방식이다.

# [ Mac / Linux 환경 ]
# [ Windows - `.sh` 대신 WSL(리눅스 환경) or `Git Bash`로 실행 ]

# 바탕화면에서 마우스 오른쪽 클릭 → Git Bash Here
# C:\Users\<사용자명>\scripts 위치에 해당 폴더 생성됨.
mkdir -p ~/scripts
mv setup_uv_project.sh ~/scripts/

# 실행 권한 부여
chmod +x ~/scripts/setup_uv_project.sh

# PATH에 등록(한번만)
echo 'export PATH="$HOME/scripts:$PATH"' >> ~/.bashrc
source ~/.bashrc

# 버전을 지정한 스크립트 실행
setup_uv_project.sh my_app 3.12

#!/bin/bash

# ----------------------------
# uv 기반 Python 프로젝트 템플릿 자동 생성기
# 사용법: bash setup_uv_project.sh <project_name> [python_version]
# 예시:  bash setup_uv_project.sh my_project 3.12
# ----------------------------

# 인자 확인
if [ -z "$1" ]; then
  echo "❌ 프로젝트 이름을 입력하세요."
  echo "사용법: bash setup_uv_project.sh <project_name> [python_version]"
  exit 1
fi

PROJECT_NAME=$1
PYTHON_VERSION=${2:-3.12}   # 기본값: 3.12

echo "🚀 프로젝트 생성 시작..."
echo "📦 이름: $PROJECT_NAME"
echo "🐍 Python 버전: $PYTHON_VERSION"
echo "----------------------------"

# 1️⃣ 프로젝트 폴더 생성
mkdir -p "$PROJECT_NAME"
cd "$PROJECT_NAME" || exit
echo "📁 프로젝트 디렉토리 생성 완료"

# 2️⃣ pyproject.toml 생성
cat <<EOF > pyproject.toml
[project]
name = "$PROJECT_NAME"
version = "0.1.0"
description = "A Python project managed by uv"
requires-python = ">=$PYTHON_VERSION,<$((${PYTHON_VERSION%%.*}+1)).0"
dependencies = []

[tool.uv]
python = "$PYTHON_VERSION"
EOF
echo "🧾 pyproject.toml 생성 완료"

# 3️⃣ main.py 생성
cat <<'EOF' > main.py
def main():
    print("🚀 Hello from your uv-managed Python project!")

if __name__ == "__main__":
    main()
EOF
echo "💻 main.py 생성 완료"

# 4️⃣ README.md 생성
cat <<EOF > README.md
# $PROJECT_NAME

This project is managed by **uv**.
EOF
echo "🗒️ README.md 생성 완료"

# 5️⃣ .gitignore 생성
cat <<'EOF' > .gitignore
.venv/
__pycache__/
*.pyc
uv.lock
EOF
echo "🙈 .gitignore 생성 완료"

# 6️⃣ uv 가상환경 생성
if ! command -v uv &> /dev/null; then
  echo "⚙️ uv가 설치되어 있지 않습니다. 설치 중..."
  pip install uv
fi

echo "⚙️ uv 가상환경 생성 중..."
uv venv --python "$PYTHON_VERSION"
if [ $? -ne 0 ]; then
  echo "❌ uv 가상환경 생성 실패. uv가 설치되어 있는지 확인하세요."
  exit 1
fi

# 7️⃣ Python 버전 고정 (pin)
uv python pin "$PYTHON_VERSION"
echo "📌 Python 버전 고정 완료"

echo "----------------------------"
echo "🎉 프로젝트 설정이 완료되었습니다!"
echo ""
echo "👉 다음 명령어로 실행하세요:"
echo "   cd $PROJECT_NAME"
echo "   source .venv/bin/activate   # (Windows: .venv\\Scripts\\activate)"
echo "   python main.py"
echo ""
echo "Happy coding with uv! 💫"

적용 과정

바탕화면 우 클릭 -> git bash 실행 -> C:\Users\roxie\scripts경로로 scripts 파일 생성됨.
우 클릭 -> .txt 파일 생성 -> 스크립트 작성 -> setup_uv_project.sh로 저장.
권한 부여 및 path 명령어 실행 후 스크립트를 실행하면 바탕화면에 프로젝트가 생성된걸 확인할 수 있다.

Python venv uv 가상환경