byteforce

CPN 한국어 자습서 · 외부 문서 한국어 미러

UV 문서 · Reference

빌드 실패

Build failures · 원문: docs.astral.sh/uv/reference/troubleshooting/build-failures/

아래는 원문을 한국어로 옮긴 미러입니다. 코드·명령은 원문 그대로이며, 가장 최신 정보는 하단 원문 링크에서 확인하세요.

개요

uv는 패키지를 설치하기 위해 사전 빌드된 wheel이 필요합니다. wheel을 사용할 수 없는 경우, uv는 소스 배포판에서 빌드를 시도합니다. 빌드 실패는 다양한 이유로 발생하며, 종종 uv 자체와는 무관합니다.

빌드 실패 인식

빌드 실패는 "The build backend returned an error" 접두사와 함께 빌드 프로세스의 stderr/stdout을 포함하여 표시됩니다. 예를 들면:

코드 · 명령
× Failed to build `numpy==1.19.5`
├─▶ The build backend returned an error
╰─▶ Call to `setuptools.build_meta:__legacy__.build_wheel()` failed (exit status: 1)

일반적인 문제 해결에 도움이 되는 힌트가 ╰─▶ 기호 뒤에 표시됩니다.

빌드 실패가 uv 전용인지 확인

빌드 격리를 사용하여 pip로 테스트하면 문제가 uv에 특정한 것인지 확인할 수 있습니다:

코드 · 명령
$ uv venv -p 3.13 --seed
$ source .venv/bin/activate
$ pip install --use-pep517 --no-cache --force-reinstall 'numpy==1.19.5'

--use-pep517 플래그는 uv와 동일한 빌드 격리 동작을 보장합니다.

uv가 패키지를 빌드하는 이유

락파일(lockfile) 생성 중 uv는 플랫폼 전반의 모든 패키지 의존성을 결정합니다. 다음 방법으로 빌드를 피합니다: - 기존 wheel 사용 - 소스 배포판에서 정적 메타데이터 추출 - 필요한 경우에만 빌드

설치 중에 uv는 일치하는 wheel이 없을 때 소스 배포판을 빌드합니다.

일반적인 빌드 실패

명령을 찾을 수 없음

gcc와 같이 누락된 명령어는 시스템 패키지 설치가 필요합니다:

코드 · 명령
$ apt install gcc

Debian/Ubuntu의 포괄적인 빌드 도구:

코드 · 명령
$ apt install build-essential

uv 관리형 Python을 사용할 때는 gcc 대신 clang이 필요할 수 있습니다.

누락된 헤더 또는 라이브러리

헤더 파일에는 개발 패키지가 필요합니다. 예를 들어, pygraphviz는 Graphviz가 필요합니다:

코드 · 명령
$ apt install libgraphviz-dev

Python.h가 없는 경우 python3-dev 패키지를 설치합니다.

누락되거나 임포트할 수 없는 모듈

일부 패키지는 선언 없이 의존성이 있다고 잘못 가정합니다. 해결 방법으로 빌드 격리를 비활성화합니다:

코드 · 명령
$ uv pip install pip setuptools
$ uv pip install chumpy --no-build-isolation-package chumpy

오래된 패키지 버전 빌드

해결 중 오래된 버전이 실패하면 하한선 제약 조건을 추가합니다:

코드 · 명령
apache-beam<=2.49.0,>2.30.0

제약 조건은 constraints.txt에 정의하거나 constraint-dependencies 설정으로 지정할 수 있습니다.

호환되지 않는 빌드 의존성 버전

build-constraint-dependencies를 사용하여 특정 빌드 의존성 버전을 강제합니다:

코드 · 명령
[tool.uv]
build-constraint-dependencies = ["setuptools!=72.0.0"]

플랫폼별 빌드 실패

지원되지 않는 플랫폼의 경우, 프로젝트 구성을 통해 필요한 플랫폼으로 해결 범위를 제한합니다.

Python 버전 비호환성

광범위한 Python 버전 범위에서는 마커를 사용하여 다른 버전을 지정합니다:

코드 · 명령
numpy>=1.23; python_version >= "3.10"
numpy<1.23; python_version < "3.10"

플랫폼별 패키지

플랫폼별 패키지의 빌드를 건너뛰기 위해 dependency-metadata 설정으로 의존성 메타데이터를 수동으로 제공합니다.

원문(영어): https://docs.astral.sh/uv/reference/troubleshooting/build-failures/ · 본 문서는 학습용 한국어 번역이며 원본의 권리는 원저작자(Astral)에게 있습니다.

원문(영어): https://docs.astral.sh/uv/reference/troubleshooting/build-failures/