설치와 명령 인식 확인

운영체제에 맞는 방법은 공식 설치 문서에서 선택합니다. 독립 설치 프로그램·패키지 관리자 등 경로가 다르므로 설치한 방법을 기록하세요. 터미널을 새로 열고 다음으로 명령 인식을 확인합니다. 아래는 독자가 사용할 예시이며 이 글의 검수에서 uv를 설치·실행한 기록은 아닙니다.

uv --version
uv python list

명령을 찾지 못하면 먼저 설치 경로와 PATH, 현재 터미널을 확인하세요. Python 버전 목록이 나온 것과 특정 Python이 설치된 것은 다릅니다. 프로젝트에서 사용할 버전은 의존 패키지의 지원 범위를 보고 정하며, 자동 다운로드가 발생할 수 있음을 고려합니다.

새 프로젝트에서 시작하기

현재 공식 프로젝트 안내의 예시는 다음과 같습니다. 기존 작업 폴더가 아닌 비어 있는 연습 위치에서 시작하세요.

uv init hello-world
cd hello-world
uv run hello-world
uv add requests

현재 안내의 기본 예제는 src/hello_world/__init__.py와 hello-world 실행 진입점을 사용합니다. 오래된 예제의 main.py를 무조건 찾지 말고 생성된 pyproject.toml과 실제 파일 구조를 확인하세요. 옵션과 uv 버전에 따라 생성 형태는 달라질 수 있습니다.

각 파일이 맡는 역할

파일·폴더 의미
pyproject.toml 프로젝트 정보·Python 조건·의존성 요구사항
.python-version 프로젝트 기본 Python 버전 선택
uv.lock 해석된 의존성의 정확한 버전 정보
.venv 실제 패키지가 설치되는 프로젝트 환경

uv add requests는 단순히 현재 Python에 패키지를 넣는 작업과 달리 프로젝트 의존성·잠금 파일·환경을 연결해 관리합니다. 잠금 파일은 uv로 관리하고 직접 버전 문자열을 고쳐 맞추지 마세요. .venv 폴더를 다른 PC에 복사하는 대신 프로젝트 정보와 잠금 파일로 환경을 준비합니다.

실행은 uv run부터 확인

uv run은 프로젝트 환경을 맞춘 뒤 명령을 실행하는 기본 경로입니다. 별도로 환경을 활성화하지 않고 사용할 수 있습니다. 반대로 터미널에서 python만 실행하면 다른 Python이 선택될 수 있으므로 현재 위치와 실행 경로를 구분하세요.

이미 만든 스크립트를 실행한다면 uv run example.py처럼 파일명을 지정합니다. 코드 오류와 패키지 설치 오류를 한꺼번에 해결하려 하지 말고 Python 선택·의존성 해석·다운로드·프로그램 실행 중 어느 단계에서 실패했는지 메시지를 읽습니다.

자체 사례: pip과 프로젝트 관리가 섞였을 때

가상의 사용자가 전역 pip install requests 후 프로젝트에서 모듈을 찾지 못한다고 가정합니다. 전역 설치가 프로젝트 .venv에 반영됐다고 볼 수 없습니다. 프로젝트 의존성으로 사용할 것인지 정한 뒤 해당 폴더에서 uv add requests와 uv run을 기준으로 확인하는 것이 사례의 해결 방향입니다.

uv pip은 pip과 비슷한 패키지 작업 인터페이스이고 uv add는 프로젝트 의존성 관리입니다. 둘을 같은 명령으로 취급하지 마세요. 실제 uv·Python 설치, 패키지 다운로드·환경 변경·예제 실행·성능 비교는 이번에 수행하지 않았습니다. 공식 명령 구조와 자체 상황 분기를 검토했습니다.

목적별 가이드

하려는 일 가이드
잠금과 설치·검사 옵션 구분하기 uv sync·lock과 locked·frozen
pip 자체의 설치·명령 오류 확인하기 Python pip 가이드
Python 진단·포맷·자동 수정 구분 확인 Ruff 가이드
Python 의존성·잠금과 가상환경 확인 Poetry Python 가이드

참고 자료