uv로 실행되는 파일에 ty import 오류가 뜰 때 해결 방법

단일 파일은 uv check --script로 검사한다

uv로는 실행되는데 타입 검사에서 외부 패키지를 못 찾는다면, 검사기가 파일의 의존성 환경을 쓰는지부터 봐야 한다. Astral이 10월 13일 공개한 uv·ty 실험 통합은 PEP 723 형식으로 의존성을 적은 스크립트를 파일별 환경에서 검사한다. 최소 버전은 uv 0.12.3과 ty 0.0.76이다.

uv check --script example.py

공식 발표에 따르면 이 명령은 스크립트에 선언된 요구사항을 사용한다. 같은 저장소의 다른 파일이 다른 Python 버전이나 패키지를 요구해도, 주변 프로젝트의 조건 하나로 묶어 검사하지 않는다. 파일 이름은 실제 검사할 경로로 바꾼다.

문제의 핵심은 패키지의 존재 여부만이 아니다. ty의 모듈 탐색 문서는 외부 패키지를 설정된 Python 환경에서 찾는다고 설명한다. 일반 프로젝트에서는 활성 가상환경이나 프로젝트의 .venv 등이 탐색 대상이 된다. 실행할 때 uv가 준비한 단일 파일용 환경을 검사기가 보지 못하면, 실행 성공과 import 진단이 동시에 나타날 수 있다.

필요한 패키지를 프로젝트가 아니라 파일 안에 선언한다

이 방식의 출발점은 파일 상단의 PEP 723 메타데이터다. uv의 스크립트 안내에 나온 명령을 이용하면 의존성 주석을 손으로 만들 필요가 없다. 새 demo.py를 준비하는 예시는 다음과 같다.

uv init --script demo.py --python 3.12
uv add --script demo.py rich
uv check --script demo.py

첫 명령은 스크립트를 만들고, 두 번째는 rich를 파일의 의존성으로 선언한다. 기존 파일을 검사하려는 경우 새 파일 생성 단계는 필요 없다. 마지막 명령은 그 선언을 사용해 타입을 검사한다.

인라인 메타데이터를 쓰는 스크립트를 uv run으로 실행하면 주변 프로젝트의 의존성은 무시된다. 따라서 프로젝트에 패키지가 설치돼 있다는 이유만으로 파일 안의 선언을 생략하면 안 된다. 실행과 검사가 참조할 요구사항을 같은 파일에 남기는 것이 이 방식의 장점이다.

VS Code에서는 ty의 scripts 설정을 켠다

편집 중 자동완성과 타입 검사를 연결하려면 uv와 ty VS Code 확장이 필요하다. 단일 파일 환경만 연결하는 설정은 다음과 같다. 기존 settings.json에 해당 항목을 추가한다.

{
  "ty.experimental.useUv": "scripts"
}

ty 설정 문서에서 scripts는 PEP 723 파일의 환경 생성·갱신을 뜻한다. on은 여기에 프로젝트 발견 기능까지 포함한다. 초기화 옵션이므로 값을 바꾼 뒤에는 편집기를 다시 시작해야 한다.

VS Code의 Restricted Mode에서는 uv 통합이 비활성화된다. 환경 준비에 의존성 설치가 포함되기 때문이다. 또한 이 설정은 ty용이다. 편집기에 남은 오류의 출처가 Pylance라면 ty 설정을 바꾼 결과와 구분해 읽어야 한다.

환경을 맞춘 뒤에도 남는 오류는 코드의 문제일 수 있다

환경이 맞아도 존재하지 않는 속성이나 맞지 않는 타입까지 사라지는 것은 아니다. 다음처럼 증상을 나누면 불필요한 패키지 재설치를 줄일 수 있다.

새 uv check는 현재 ty를 실행하는 진입점이다. Ruff 연동은 공식 발표에서 후속 계획으로 제시됐다. 기존 린트·테스트를 지우는 대신, 우선 단일 파일 하나의 선언과 검사 환경을 맞추는 데 적용할 수 있다.