Python. uv init --python 3.12 와 uv python pin 3.12 의 차이

uv init --python 3.12 와 uv python pin 3.12 의 차이는 “프로젝트가 허용하는 Python 범위”와 “내 로컬에서 실제로 쓸 Python 선택”의 차이입니다.

uv init --python 3.12

이건 보통 pyproject.toml에 이런 식으로 들어갑니다.

[project]
requires-python = ">=3.12"

즉, 의미는:

이 프로젝트는 Python 3.12 이상에서 동작한다.

입니다. 그래서 3.12도 가능하고, 3.13도 가능하고, 나중에 3.14도 조건상 가능할 수 있습니다.

반면:

uv python pin 3.12

이건 프로젝트 디렉터리에 보통 .python-version 파일을 만듭니다.

3.12

의미는:

이 프로젝트에서 uv가 Python을 고를 때 3.12 계열을 우선 사용하라.

입니다.

그래서 차이를 예로 들면:

uv init --python 3.12
uv sync

만 했을 때는 requires-python = ">=3.12" 조건만 만족하면 되므로, 내 컴퓨터에 3.13이 더 적절하게 발견되면 3.13을 쓸 수 있습니다.

하지만:

uv init --python 3.12
uv python pin 3.12
uv sync

까지 하면, uv는 .python-version을 보고 3.12를 쓰려 합니다.

정리하면:

상황	의미	실제 Python 선택
uv init --python 3.12만 함	프로젝트는 3.12 이상 필요	3.12, 3.13 등 가능
uv python pin 3.12도 함	이 로컬 프로젝트는 3.12를 사용	3.12 계열로 고정
둘 다 안 함	uv 기본값/발견된 Python 사용	환경에 따라 달라짐

실무적으로는 이렇게 보면 됩니다.

라이브러리 프로젝트라면 보통 requires-python만 넓게 잡는 경우가 많습니다.

uv init --python 3.12

이 경우 “이 패키지는 3.12 이상 지원”이라는 선언이 중요합니다.

애플리케이션 프로젝트라면 pin까지 하는 편이 더 안전합니다.

uv init --python 3.12
uv python pin 3.12

이 경우 팀원이나 CI에서 “다들 3.12로 개발/실행”하게 만들 수 있습니다.

정확히 확인하려면 아래를 보면 됩니다.

type pyproject.toml
type .python-version
uv run python -c "import sys; print(sys.version); print(sys.executable)"

한 줄로 말하면:

uv init --python 3.12는 호환성 선언이고, uv python pin 3.12는 실행 버전 선택입니다.