uv (Python 패키지 매니저)

​

사전 준비

• Windows 10 이상의 PC
• 인터넷 연결
• PowerShell (Windows에 기본으로 설치되어 있습니다)

1

uv 공식 문서 확인하기 (선택 사항)

uv에 대해 더 자세히 알고 싶다면, 웹 브라우저에서 docs.astral.sh/uv에 접속하여 공식 문서를 확인할 수 있습니다. 설치 방법, 사용법, 기능 목록 등이 상세히 안내되어 있습니다.

공식 문서를 꼭 읽지 않아도 됩니다. 아래 단계를 따라하면 바로 설치할 수 있습니다.

2

PowerShell 열기

키보드에서 Windows 키를 누르고 “PowerShell”을 입력한 후 Windows PowerShell을 클릭하여 실행합니다.파란색(또는 검은색) 배경의 터미널 창이 열리면 준비가 된 것입니다.

3

설치 명령어 실행하기

PowerShell 창에 아래 명령어를 복사하여 붙여넣고 Enter를 누르세요. (명령어를 마우스 오른쪽 클릭으로 붙여넣을 수 있습니다.)

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

이 명령어가 하는 일을 간단히 설명하면:

• irm - 인터넷에서 설치 스크립트를 다운로드합니다
• iex - 다운로드한 스크립트를 실행합니다
• -ExecutionPolicy ByPass - 이번 한 번만 스크립트 실행 제한을 해제합니다

4

설치 완료 확인하기

설치가 완료되면 다음과 같은 메시지가 표시됩니다:

• Downloading uv 0.10.4 - uv를 다운로드했다는 뜻입니다
• Installing to C:\Users\사용자이름\.local\bin - 이 경로에 설치되었습니다
• everything's installed! - 모든 설치가 완료되었습니다

화면에 PATH(경로) 설정을 위한 추가 명령어가 안내됩니다. 안내된 대로 아래 명령어를 실행합니다.

$env:Path = "C:\Users\사용자이름\.local\bin;$env:Path"

PATH란 컴퓨터가 명령어를 찾을 때 확인하는 폴더 목록입니다. uv가 설치된 폴더를 PATH에 추가해야 어디서든 uv 명령어를 사용할 수 있습니다. 터미널을 새로 열면 자동으로 적용되므로, 잘 모르겠다면 터미널을 닫고 새로 열어주세요.

5

uv가 정상적으로 설치되었는지 확인하기

새 PowerShell 창을 열고 다음 명령어를 입력합니다.

uv help

uv의 도움말(사용 가능한 명령어 목록, 옵션 설명 등)이 출력되면 설치가 정상적으로 완료된 것입니다.

만약 “uv는 인식할 수 없는 명령입니다”라는 오류가 나온다면, 터미널을 완전히 닫고 새로 열어 보세요.

6

테스트용 프로젝트 폴더 만들기

uv가 정상 동작하는지 확인하기 위해 테스트 폴더를 생성합니다. 아래 명령어를 차례대로 입력합니다.

mkdir test
cd .\test\

첫 번째 명령어(mkdir test)는 “test”라는 이름의 폴더를 만듭니다. 두 번째 명령어(cd .\test\)는 방금 만든 폴더 안으로 이동합니다.

7

Python 프로젝트 만들고 가상환경 생성하기

다음 두 가지 명령어를 차례대로 입력합니다.

uv init --python 3.13
uv venv

• uv init --python 3.13 - Python 3.13 버전을 사용하는 새 프로젝트를 만듭니다. pyproject.toml이라는 프로젝트 설정 파일이 생성됩니다.
• uv venv - 가상환경을 생성합니다. 해당 Python 버전이 내 PC에 없으면 uv가 자동으로 다운로드합니다.

가상환경(Virtual Environment)이란? Python 프로젝트마다 독립된 공간을 만들어주는 기능입니다. 프로젝트 A에서 설치한 라이브러리가 프로젝트 B에 영향을 주지 않도록 격리해 줍니다. 프로젝트를 만들 때 가상환경을 사용하는 것이 좋은 습관입니다.

8

가상환경 활성화 시 오류가 발생하는 경우

가상환경을 활성화하기 위해 아래 명령어를 입력합니다.

.\.venv\Scripts\activate

이때 빨간색 오류 메시지(PSSecurityException)가 나타날 수 있습니다. 이것은 Windows PowerShell의 보안 정책 때문에 발생하는 것으로, 스크립트 파일(.ps1) 실행이 기본적으로 차단되어 있기 때문입니다.

이 오류는 다음 단계에서 해결할 수 있습니다. 오류가 나타나지 않는 경우, 다음 두 단계를 건너뛰고 “가상환경 활성화 성공” 단계로 이동합니다.

9

PowerShell 실행 정책 변경하기 (관리자 권한 필요)

이 오류를 해결하려면 PowerShell의 실행 정책을 변경해야 합니다.

1. 현재 열려 있는 PowerShell 창을 닫습니다.
2. Windows 키를 누르고 “PowerShell”을 입력합니다.
3. Windows PowerShell을 오른쪽 클릭하고 **“관리자 권한으로 실행”**을 선택합니다.
4. 관리자 권한 PowerShell 창에서 아래 명령어를 입력하고 Enter를 누르세요.

Set-ExecutionPolicy RemoteSigned

확인 메시지가 나타나면 A (모두 예)를 입력하고 Enter를 누르세요.

RemoteSigned 정책은 “내 PC에서 직접 만든 스크립트는 자유롭게 실행할 수 있고, 인터넷에서 다운로드한 스크립트는 서명이 있어야 실행할 수 있다”는 뜻입니다. 개발자에게 권장되는 안전한 설정입니다.

10

가상환경 활성화 성공 확인하기

실행 정책을 변경한 후, 일반 PowerShell 창을 새로 열고 테스트 폴더로 이동하여 다시 활성화 명령어를 실행합니다.

cd test
.\.venv\Scripts\activate

명령어가 정상적으로 실행되면, 프롬프트(명령어 입력 줄) 앞에 (test)라는 표시가 나타납니다. 이것이 보이면 가상환경이 성공적으로 활성화된 것입니다.

가상환경이 활성화된 상태에서 uv pip install 패키지이름으로 필요한 라이브러리를 설치하거나, uv add 패키지이름으로 프로젝트 의존성을 관리할 수 있습니다. 가상환경을 비활성화하려면 deactivate를 입력합니다.

​

설치 점검 목록

• 관리자 권한/필수 도구 등 사전 요구사항을 먼저 확인했습니다.
• 설치 후 버전 확인 명령어(--version)를 실행해 정상 설치를 검증했습니다.
• PATH/환경변수 변경이 필요한 경우 터미널을 다시 열어 적용 여부를 확인했습니다.
• 문제가 생겼을 때를 대비해 설치 로그 또는 스크린샷을 남겼습니다.

​

문제 해결 가이드

• 설치 파일이 실행되지 않으면 관리자 권한으로 다시 실행합니다.
• 명령어가 인식되지 않으면 터미널을 새로 열고 PATH 반영 여부를 확인합니다.
• 버전이 맞지 않으면 기존 설치를 정리한 뒤 권장 버전으로 재설치합니다.
• 설정 변경 후 동작이 이상하면 시스템 재시작 후 다시 확인합니다.

​

관련 문서