프로젝트 정보·잠금·환경 나누기

pyproject.toml은 필요한 패키지의 조건을, uv.lock은 해석된 정확한 버전을 기록합니다. .venv는 실제 실행 환경입니다. 요구사항 파일을 수정해도 환경이 저절로 바뀌었다고 판단하지 말고 어느 단계까지 진행했는지 확인하세요.

uv는 run·sync 같은 프로젝트 명령에서 자동으로 잠금과 환경 갱신을 연결합니다. 명령 이름이 실행이라도 의존성 해석·설치가 발생할 수 있으므로, 재현성을 검사할 때는 명시적인 옵션과 버전을 기록하는 편이 좋습니다.

명령과 옵션의 차이

명령·옵션 확인하는 일 주의할 점
uv lock 요구사항 해석·잠금 생성 또는 갱신 환경 설치와 구분
uv sync 프로젝트 환경을 의존성과 맞춤 기본적으로 불필요 패키지를 제거하는 exact 동기화
uv sync --locked 잠금 최신성 검사 후 환경 맞춤 잠금이 낡았으면 갱신 대신 오류
uv sync --frozen 기존 잠금으로 환경 맞춤 요구사항과 최신성 대조를 생략
uv run --no-sync 환경 동기화를 생략하고 실행 현재 환경이 맞다는 보장은 따로 필요

잠금 파일 검사만 하려면 uv lock --check를 사용할 수 있습니다. 새 버전의 패키지가 공개됐다는 이유만으로 기존 잠금이 낡았다고 판정하지는 않습니다. 프로젝트 메타데이터와 잠금의 일치 여부가 핵심입니다.

검사용 흐름과 변경용 흐름 구분

다음은 준비된 연습 프로젝트에서 사용할 명령 예시입니다. 실제 계정이나 프로젝트에서 실행한 로그가 아닙니다.

# 현재 요구사항과 잠금 파일의 일치 여부 검사
uv lock --check
# 잠금 파일을 갱신하지 않고 환경을 맞춤
uv sync --locked
# 같은 조건에서 프로그램 실행
uv run --locked example.py

의존성을 의도적으로 바꿀 때는 변경 내용을 검토하고 잠금을 갱신합니다. 오류를 없애기 위해 무조건 --frozen을 붙이면 요구사항과 잠금의 불일치가 가려질 수 있습니다. 잠금을 지우는 방식보다 어떤 의존성 조건이 바뀌었는지 먼저 확인하세요.

자체 사례: pyproject만 바꾸고 frozen 실행

가상의 프로젝트에서 새 의존성을 pyproject.toml에만 추가했다고 가정합니다. 기존 uv.lock으로 --frozen 동기화를 통과해도 새 의존성이 반영됐다고 볼 수 없습니다. 이 사례에서는 최신성을 확인하는 --locked가 불일치를 드러내고, 변경 의도 확인 후 잠금을 갱신하는 것이 순서입니다.

환경에 우연히 설치된 패키지 때문에 실행되는 상황도 주의하세요. 현재 문서에서 uv sync는 기본 exact, uv run은 기본 inexact 동기화입니다. 후자는 필요 없는 패키지를 기본적으로 제거하지 않습니다. 두 명령이 환경 정리까지 똑같이 수행한다고 가정하지 마세요.

실패 단계에 따라 읽을 메시지

잠금 불일치라면 프로젝트 조건과 잠금 변경을, 해석 실패라면 Python·패키지 버전 제약을 확인합니다. 다운로드 실패와 프로그램 자체 예외는 별도 문제입니다. 다른 운영체제에서도 잠금 파일을 공유할 수 있지만 모든 플랫폼에서 같은 바이너리가 실행된다는 보장은 아닙니다.

이번 검수는 공식 옵션 의미·명령 구조와 자체 불일치 사례를 확인한 범위입니다. 실제 uv 설치·의존성 해석·패키지 설치·환경 삭제·프로그램 실행·CI 성공을 검증한 결과가 아닙니다.

목적별 가이드

하려는 일 가이드
uv 프로젝트 처음 만들기 uv 설치와 프로젝트 시작
pip 명령 자체의 오류 확인하기 Python pip 가이드

참고 자료