> ## Documentation Index
> Fetch the complete documentation index at: https://docs.baeum.ai.kr/llms.txt
> Use this file to discover all available pages before exploring further.
# uv (Python 패키지 매니저)
uv는 Python 프로젝트를 관리하는 데 필요한 거의 모든 기능을 하나로 모아놓은 도구입니다. 기존에는 Python을 설치하고(pyenv), 가상환경을 만들고(venv), 패키지를 설치하는(pip) 과정을 각각 다른 도구로 해야 했는데, uv 하나면 이 모든 것을 한 번에 해결할 수 있습니다. Rust라는 언어로 만들어져서 기존 도구들보다 10\~100배 빠릅니다.
## 사전 준비
* Windows 10 이상의 PC
* 인터넷 연결
* PowerShell (Windows에 기본으로 설치되어 있습니다)
uv를 사용하면 Python을 별도로 설치할 필요가 없습니다. uv가 알아서 필요한 Python 버전을 자동으로 다운로드하고 관리해 줍니다.
uv에 대해 더 자세히 알고 싶다면, 웹 브라우저에서 [docs.astral.sh/uv](https://docs.astral.sh/uv)에 접속하여 공식 문서를 확인할 수 있습니다. 설치 방법, 사용법, 기능 목록 등이 상세히 안내되어 있습니다.
공식 문서를 꼭 읽지 않아도 됩니다. 아래 단계를 따라하면 바로 설치할 수 있습니다.
키보드에서 `Windows 키`를 누르고 "PowerShell"을 입력한 후 **Windows PowerShell**을 클릭하여 실행합니다.
파란색(또는 검은색) 배경의 터미널 창이 열리면 준비가 된 것입니다.
PowerShell 창에 아래 명령어를 복사하여 붙여넣고 Enter를 누르세요. (명령어를 마우스 오른쪽 클릭으로 붙여넣을 수 있습니다.)
```powershell theme={null}
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```
이 명령어가 하는 일을 간단히 설명하면:
* `irm` - 인터넷에서 설치 스크립트를 다운로드합니다
* `iex` - 다운로드한 스크립트를 실행합니다
* `-ExecutionPolicy ByPass` - 이번 한 번만 스크립트 실행 제한을 해제합니다
설치가 완료되면 다음과 같은 메시지가 표시됩니다:
* `Downloading uv 0.10.4` - uv를 다운로드했다는 뜻입니다
* `Installing to C:\Users\사용자이름\.local\bin` - 이 경로에 설치되었습니다
* `everything's installed!` - 모든 설치가 완료되었습니다
화면에 PATH(경로) 설정을 위한 추가 명령어가 안내됩니다. 안내된 대로 아래 명령어를 실행합니다.
```powershell theme={null}
$env:Path = "C:\Users\사용자이름\.local\bin;$env:Path"
```
PATH란 컴퓨터가 명령어를 찾을 때 확인하는 폴더 목록입니다. uv가 설치된 폴더를 PATH에 추가해야 어디서든 `uv` 명령어를 사용할 수 있습니다. 터미널을 새로 열면 자동으로 적용되므로, 잘 모르겠다면 터미널을 닫고 새로 열어주세요.
새 PowerShell 창을 열고 다음 명령어를 입력합니다.
```powershell theme={null}
uv help
```
uv의 도움말(사용 가능한 명령어 목록, 옵션 설명 등)이 출력되면 설치가 정상적으로 완료된 것입니다.
만약 "uv는 인식할 수 없는 명령입니다"라는 오류가 나온다면, 터미널을 완전히 닫고 새로 열어 보세요.
uv가 정상 동작하는지 확인하기 위해 테스트 폴더를 생성합니다. 아래 명령어를 차례대로 입력합니다.
```powershell theme={null}
mkdir test
cd .\test\
```
첫 번째 명령어(`mkdir test`)는 "test"라는 이름의 폴더를 만듭니다. 두 번째 명령어(`cd .\test\`)는 방금 만든 폴더 안으로 이동합니다.
다음 두 가지 명령어를 차례대로 입력합니다.
```powershell theme={null}
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에 영향을 주지 않도록 격리해 줍니다. 프로젝트를 만들 때 가상환경을 사용하는 것이 좋은 습관입니다.
가상환경을 활성화하기 위해 아래 명령어를 입력합니다.
```powershell theme={null}
.\.venv\Scripts\activate
```
이때 빨간색 오류 메시지(PSSecurityException)가 나타날 수 있습니다. 이것은 Windows PowerShell의 보안 정책 때문에 발생하는 것으로, 스크립트 파일(.ps1) 실행이 기본적으로 차단되어 있기 때문입니다.
이 오류는 다음 단계에서 해결할 수 있습니다. 오류가 나타나지 않는 경우, 다음 두 단계를 건너뛰고 "가상환경 활성화 성공" 단계로 이동합니다.
이 오류를 해결하려면 PowerShell의 실행 정책을 변경해야 합니다.
1. 현재 열려 있는 PowerShell 창을 닫습니다.
2. `Windows 키`를 누르고 "PowerShell"을 입력합니다.
3. **Windows PowerShell**을 오른쪽 클릭하고 \*\*"관리자 권한으로 실행"\*\*을 선택합니다.
4. 관리자 권한 PowerShell 창에서 아래 명령어를 입력하고 Enter를 누르세요.
```powershell theme={null}
Set-ExecutionPolicy RemoteSigned
```
확인 메시지가 나타나면 **A** (모두 예)를 입력하고 Enter를 누르세요.
**RemoteSigned** 정책은 "내 PC에서 직접 만든 스크립트는 자유롭게 실행할 수 있고, 인터넷에서 다운로드한 스크립트는 서명이 있어야 실행할 수 있다"는 뜻입니다. 개발자에게 권장되는 안전한 설정입니다.
실행 정책을 변경한 후, 일반 PowerShell 창을 새로 열고 테스트 폴더로 이동하여 다시 활성화 명령어를 실행합니다.
```powershell theme={null}
cd test
.\.venv\Scripts\activate
```
명령어가 정상적으로 실행되면, 프롬프트(명령어 입력 줄) 앞에 `(test)`라는 표시가 나타납니다. 이것이 보이면 가상환경이 성공적으로 활성화된 것입니다.
가상환경이 활성화된 상태에서 `uv pip install 패키지이름`으로 필요한 라이브러리를 설치하거나, `uv add 패키지이름`으로 프로젝트 의존성을 관리할 수 있습니다. 가상환경을 비활성화하려면 `deactivate`를 입력합니다.
## 설치 점검 목록
* 관리자 권한/필수 도구 등 사전 요구사항을 먼저 확인했습니다.
* 설치 후 버전 확인 명령어(`--version`)를 실행해 정상 설치를 검증했습니다.
* PATH/환경변수 변경이 필요한 경우 터미널을 다시 열어 적용 여부를 확인했습니다.
* 문제가 생겼을 때를 대비해 설치 로그 또는 스크린샷을 남겼습니다.
## 문제 해결 가이드
* 설치 파일이 실행되지 않으면 관리자 권한으로 다시 실행합니다.
* 명령어가 인식되지 않으면 터미널을 새로 열고 PATH 반영 여부를 확인합니다.
* 버전이 맞지 않으면 기존 설치를 정리한 뒤 권장 버전으로 재설치합니다.
* 설정 변경 후 동작이 이상하면 시스템 재시작 후 다시 확인합니다.
## 관련 문서
운영체제별 설치 흐름을 다시 확인합니다.
다음 설치 단계를 이어서 진행합니다.