잠금 및 동기화

잠금 파일 생성

프로젝트 환경을 사용하는 uv 명령어 실행 시 잠금 파일이 생성되거나 업데이트된다. 예를 들어 uv sync와 uv run 명령어를 사용할 때 이 작업이 수행된다. 또한 uv lock 명령어를 통해 명시적으로 잠금 파일을 생성하거나 업데이트할 수도 있다:

$ uv lock

lockfile 내보내기

다른 도구나 워크플로우와 uv를 통합해야 한다면, uv export --format requirements-txt 명령어를 사용해 uv.lock을 requirements.txt 형식으로 내보낼 수 있다. 이렇게 생성된 requirements.txt 파일은 uv pip install이나 pip 같은 다른 도구로 설치할 수 있다.

일반적으로 uv.lock과 requirements.txt 파일을 동시에 사용하는 것은 권장하지 않는다. uv.lock 파일을 내보내야 하는 상황이라면, 해당 사용 사례에 대해 이슈를 열어 논의하는 것을 고려해보자.

lockfile이 최신 상태인지 확인하기

uv sync와 uv run 명령 실행 중에 lockfile이 업데이트되지 않도록 하려면 --frozen 플래그를 사용한다.

uv run 명령 실행 중에 환경이 업데이트되지 않도록 하려면 --no-sync 플래그를 사용한다.

lockfile이 프로젝트 메타데이터와 일치하는지 확인하려면 --locked 플래그를 사용한다. lockfile이 최신 상태가 아닌 경우, lockfile을 업데이트하는 대신 오류가 발생한다.

uv lock 명령에 --check 플래그를 전달해 lockfile이 최신 상태인지 확인할 수도 있다:

$ uv lock --check

이 플래그는 다른 명령에서 사용하는 --locked 플래그와 동일한 역할을 한다.

잠긴 패키지 버전 업그레이드

기본적으로 uv.lock 파일이 존재할 때 uv sync와 uv lock 명령을 실행하면, uv는 잠긴 패키지 버전을 우선적으로 사용한다. 프로젝트의 의존성 제약 조건이 이전에 잠긴 버전을 제외하지 않는 한, 패키지 버전은 변경되지 않는다.

모든 패키지를 업그레이드하려면 다음 명령을 실행한다:

$ uv lock --upgrade

다른 모든 패키지의 잠긴 버전을 유지하면서 특정 패키지만 최신 버전으로 업그레이드하려면 다음 명령을 사용한다:

$ uv lock --upgrade-package <package>

특정 패키지를 특정 버전으로 업그레이드하려면 다음 명령을 실행한다:

$ uv lock --upgrade-package <package>==<version>

모든 경우에 업그레이드는 프로젝트의 의존성 제약 조건 내에서만 이루어진다. 예를 들어, 프로젝트가 특정 패키지에 대해 상한 버전을 정의했다면, 업그레이드는 그 버전을 넘어서지 않는다.

Note

uv는 Git 의존성에도 비슷한 로직을 적용한다. 예를 들어, Git 의존성이 main 브랜치를 참조하고 있다면, --upgrade나 --upgrade-package 플래그를 사용하지 않는 한, uv는 main 브랜치의 최신 커밋보다는 기존 uv.lock 파일에 기록된 커밋 SHA를 우선적으로 사용한다.