uv를 사용하는 방법을 다룹니다. uv는 Rust로 작성된 매우 빠른 Python 패키지 및 프로젝트 관리자입니다.
uv는 다양한 설치 방법을 제공하고 있습니다. 본 문서에서는 공식 설치 프로그램을 사용한 uv 설치 방법을 다룹니다.
단계별로 번호를 부여하여 윈도우와 우분투(맥OS도 동일하게 동작할듯합니다)에서 실행하는 것을 보여줍니다.
2025.3.20 최초작성 . uv를 간단히 사용해봤습니다.
2025.9.4 업데이트
1. uv 설치
macOS and Linux
curl -LsSf https://astral.sh/uv/install.sh | sh |
$ curl -LsSf https://astral.sh/uv/install.sh | sh
downloading uv 0.8.15 x86_64-unknown-linux-gnu
no checksums to verify
installing to /home/webnautes/.local/bin
uv
uvx
everything's installed! |
Windows
명령 프롬프트에서 실행합니다.
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" |
C:\Users\freem>powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
Downloading uv 0.8.15 (x86_64-pc-windows-msvc) Installing to C:\Users\freem\.local\bin
uv.exe
uvx.exe
uvw.exe
everything's installed!
To add C:\Users\freem\.local\bin to your PATH, either restart your shell or run:
set Path=C:\Users\freem\.local\bin;%Path% (cmd)
$env:Path = "C:\Users\freem\.local\bin;$env:Path" (powershell) |
명령 프롬프트를 다시 실행한 후 uv -V 명령어를 실행하여 설치된 uv가 사용가능한지와 버전을 확인합니다.
C:\Users\freem>uv -V
uv 0.8.15 (8473ecba1 2025-09-03) |
uv의 설치를 제거하려면 다음처럼 진행하세요.
윈도우의 경우엔 PowerShell에서 수행해야합니다.
1.저장된 데이터 정리
uv cache clean
rm -r "$(uv python dir)"
rm -r "$(uv tool dir)" |
2.uv 바이너리 파일 제거
macOS and Linux
rm ~/.local/bin/uv ~/.local/bin/uvx |
Windows
rm $HOME\.local\bin\uv.exe
rm $HOME\.local\bin\uvx.exe
rm $HOME\.local\bin\uvw.exe |
2. 프로젝트 생성
새로운 프로젝트를 생성하고 초기 파일들을 설정합니다. 현재 위치에 init 뒤에 적은 이름의 디렉토리가 생성됩니다. 사용할 파이썬 버전도 지정하고 있습니다.
uv init my-project --python 파이썬버전 |
Windows
파이썬 3.13을 사용하도록 myproject 디렉토리에 프로젝트를 생성합니다.
C:\Users\freem>uv init myproject --python 3.13
Initialized project `myproject` at `C:\Users\freem\myproject` |
생성된 디렉토리 내에 파일들이 생성됩니다.
C:\Users\freem>cd myproject
C:\Users\freem\myproject>dir
C 드라이브의 볼륨에는 이름이 없습니다.
볼륨 일련 번호: F286-9FFE
C:\Users\freem\myproject 디렉터리
2025-09-04 오후 09:55 <DIR> .
2025-09-04 오후 09:55 <DIR> ..
2025-09-04 오후 09:55 109 .gitignore
2025-09-04 오후 09:55 5 .python-version
2025-09-04 오후 09:55 87 main.py
2025-09-04 오후 09:55 155 pyproject.toml
2025-09-04 오후 09:55 0 README.md
5개 파일 356 바이트
2개 디렉터리 341,687,693,312 바이트 남음 |
uv python list 명령으로 설치된 파이썬을 확인합니다. 윈도우의 경우엔 파이썬이 설치되지 않았습니다. 우분투와 달리 설치할 파이썬 버전 지정하는 명령이 동작하지 않았습니다.
C:\Users\freem\myproject>uv python list
cpython-3.14.0rc2-windows-x86_64-none <download available>
cpython-3.14.0rc2+freethreaded-windows-x86_64-none <download available>
cpython-3.13.7-windows-x86_64-none <download available>
cpython-3.13.7+freethreaded-windows-x86_64-none <download available>
cpython-3.12.11-windows-x86_64-none <download available>
cpython-3.11.13-windows-x86_64-none <download available>
cpython-3.10.18-windows-x86_64-none <download available>
cpython-3.9.23-windows-x86_64-none <download available>
cpython-3.8.20-windows-x86_64-none <download available>
pypy-3.11.13-windows-x86_64-none <download available>
pypy-3.10.16-windows-x86_64-none <download available>
pypy-3.9.19-windows-x86_64-none <download available>
pypy-3.8.16-windows-x86_64-none <download available>
graalpy-3.11.0-windows-x86_64-none <download available>
graalpy-3.10.0-windows-x86_64-none <download available> |
다음처럼 파이썬을 설치할 수 있습니다.
C:\Users\freem\myproject>uv python install 3.13
Installed Python 3.13.7 in 3.16s
+ cpython-3.13.7-windows-x86_64-none (python3.13.exe)
C:\Users\freem\myproject>uv python list
cpython-3.14.0rc2-windows-x86_64-none <download available>
cpython-3.14.0rc2+freethreaded-windows-x86_64-none <download available>
cpython-3.13.7-windows-x86_64-none C:\Users\freem\AppData\Roaming\uv\python\cpython-3.13.7-windows-x86_64-none\python.exe
cpython-3.13.7-windows-x86_64-none C:\Users\freem\.local\bin\python3.13.exe
cpython-3.13.7-windows-x86_64-none <download available>
cpython-3.13.7+freethreaded-windows-x86_64-none <download available>
cpython-3.12.11-windows-x86_64-none <download available>
cpython-3.11.13-windows-x86_64-none <download available>
cpython-3.10.18-windows-x86_64-none <download available>
cpython-3.9.23-windows-x86_64-none <download available>
cpython-3.8.20-windows-x86_64-none <download available>
pypy-3.11.13-windows-x86_64-none <download available>
pypy-3.10.16-windows-x86_64-none <download available>
pypy-3.9.19-windows-x86_64-none <download available>
pypy-3.8.16-windows-x86_64-none <download available>
graalpy-3.11.0-windows-x86_64-none <download available>
graalpy-3.10.0-windows-x86_64-none <download available> |
Ubuntu
파이썬 3.13을 사용하도록 myproject 디렉토리에 프로젝트를 생성합니다.
$ uv init myproject --python 3.13
Initialized project `myproject` at `/home/webnautes/myproject` |
생성된 디렉토리 내에 파일들이 생성됩니다.
$ cd my-project/
$ ls -al
합계 28
drwxrwxr-x 3 webnautes webnautes 4096 9월 4 17:43 .
drwxr-x--- 40 webnautes webnautes 4096 9월 4 17:43 ..
drwxrwxr-x 7 webnautes webnautes 4096 9월 4 17:43 .git
-rw-rw-r-- 1 webnautes webnautes 109 9월 4 17:43 .gitignore
-rw-rw-r-- 1 webnautes webnautes 5 9월 4 17:43 .python-version
-rw-rw-r-- 1 webnautes webnautes 0 9월 4 17:43 README.md
-rw-rw-r-- 1 webnautes webnautes 87 9월 4 17:43 main.py
-rw-rw-r-- 1 webnautes webnautes 155 9월 4 17:43 pyproject.toml |
우분투의 경우엔 파이썬이 설치되었습니다.
cpython-3.10.12-linux-x86_64-gnu 항목중 /usr/bin/python3.10와 /usr/bin/python3는 우분투에 기존에 설치되어 있는 파이썬이 인식된 것입니다.
새로 설치한 Python 3.13은 cpython-3.13.7-linux-x86_64-gnu 입니다. 경로가 /home/webnautes/.local/share/uv/python/ 이하로 되어 있습니다.
$ uv python list
cpython-3.14.0rc2-linux-x86_64-gnu <download available>
cpython-3.14.0rc2+freethreaded-linux-x86_64-gnu <download available>
cpython-3.13.7-linux-x86_64-gnu /home/webnautes/.local/share/uv/python/cpython-3.13.7-linux-x86_64-gnu/bin/python3.13
cpython-3.13.7+freethreaded-linux-x86_64-gnu <download available>
cpython-3.12.11-linux-x86_64-gnu <download available>
cpython-3.11.13-linux-x86_64-gnu <download available>
cpython-3.10.18-linux-x86_64-gnu <download available>
cpython-3.10.12-linux-x86_64-gnu /usr/bin/python3.10
cpython-3.10.12-linux-x86_64-gnu /usr/bin/python3 -> python3.10
cpython-3.9.23-linux-x86_64-gnu <download available>
cpython-3.8.20-linux-x86_64-gnu <download available>
pypy-3.11.13-linux-x86_64-gnu <download available>
pypy-3.10.16-linux-x86_64-gnu <download available>
pypy-3.9.19-linux-x86_64-gnu <download available>
pypy-3.8.16-linux-x86_64-gnu <download available>
graalpy-3.11.0-linux-x86_64-gnu <download available>
graalpy-3.10.0-linux-x86_64-gnu <download available>
graalpy-3.8.5-linux-x86_64-gnu <download available> |
다음처럼 원하는 디렉터리에서 프로젝트를 초기화할 수 있습니다:
mkdir hello-world
cd hello-world
uv init |
3. 가상환경 생성
가상 환경을 생성합니다.
Windows
C:\Users\freem\myproject>uv venv
Using CPython 3.13.7
Creating virtual environment at: .venv
Activate with: .venv\Scripts\activate |
Ubuntu
$ uv venv
Using CPython 3.13.7
Creating virtual environment at: .venv
Activate with: source .venv/bin/activate |
4. 가상환경 활성화
가상환경을 활성화합니다. 프롬프트 맨 앞에 폴더 이름이 붙습니다..
Windows
C:\Users\freem\myproject>.venv\Scripts\activate
실행후 화면이 지워집니다.
(myproject) C:\Users\freem\myproject> |
Ubuntu
source .venv/bin/activate
$ source .venv/bin/activate
(myproject)$ |
5.패키지 설치
5번부터는 공통적인 내용이라 윈도우에서 진행한 내용만 남겨둡니다.
프로젝트에 패키지를 추가하려면 다음 명령어를 사용합니다:
opencv-python 패키지를 설치합니다.
(myproject) C:\Users\freem\myproject>uv add opencv-python
Resolved 3 packages in 176ms
Prepared 2 packages in 4.54s
Installed 2 packages in 192ms
+ numpy==2.2.6
+ opencv-python==4.12.0.88 |
설치된 패키지 목록을 확인합니다.
(myproject) C:\Users\freem\myproject>uv pip list
Package Version
------------- ---------
numpy 2.2.6
opencv-python 4.12.0.88 |
pyproject.toml 파일에서도 확인이 가능합니다. 같이 설치되었던 numpy는 기록되어 있지 않습니다.
(myproject) C:\Users\freem\myproject>type pyproject.toml
[project]
name = "myproject"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.13"
dependencies = [
"opencv-python>=4.12.0.88",
] |
대안으로 다음 명령을 사용하여 패키지를 설치할 수도 있습니다.
설치할 버전 제약 조건을 지정하거나 다른 출처를 지정할 수도 있습니다:
# 설치할 패키지의 버전을 지정합니다.
uv add 'requests==2.31.0'
# 패키지를 설치할 때 사용할 주소를 지정합니다.
uv add git+https://github.com/psf/requests |
6. 파이썬 코드 실행
파이썬 코드를 실행합니다. 프로젝트 생성시 현재 디렉토리에 main.py 파일이 생성되어 있습니다.
(myproject) C:\Users\freem\myproject>uv run main.py
Hello from myproject! |
main.py 파일을 다음처럼 수정합니다.
import cv2
print(cv2.__version__) |
다시 실행해봅니다.
(myproject) C:\Users\freem\myproject>uv run main.py
4.12.0 |
7. 패키지 제거
패키지를 제거합니다.
opencv-python 패키지를 제거해봅니다.
(myproject) C:\Users\freem\myproject>uv remove opencv-python
Resolved 1 package in 11ms
Uninstalled 2 packages in 98ms
- numpy==2.2.6
- opencv-python==4.12.0.88
(myproject) C:\Users\freem\myproject>uv pip list
(myproject) C:\Users\freem\myproject> |
대안으로 다음 명령을 사용하여 패키지를 삭제제할 수도 있습니다.
8.가상환경 종료
가상환경을 종료합니다.
(myproject) C:\Users\freem\myproject>deactivate
C:\Users\freem\myproject> |
파이썬 스크립트에 인수를 제공할 수 있습니다:
example.py
import sys
print(" ".join(sys.argv[1:])) |
uv run example.py test
uv run example.py hello world! |
또한, 파이썬 스크립트를 표준 입력(stdin)에서 직접 읽을 수 있습니다:
echo 'print("hello world!")' | uv run - |
프로젝트 구조
프로젝트는 uv가 프로젝트를 관리할 수 있게 하는 몇 가지 중요한 부분으로 구성됩니다. uv init으로 생성된 파일 외에도, uv는 프로젝트 명령어(예: uv run, uv sync, uv lock)를 처음 실행할 때 프로젝트 루트에 가상 환경과 uv.lock 파일을 생성합니다.
전체 프로젝트 구조는 다음과 같습니다:
.
├── .venv
│ ├── bin
│ ├── lib
│ └── pyvenv.cfg
├── .python-version
├── README.md
├── main.py
├── pyproject.toml
└── uv.lock |
pyproject.toml
pyproject.toml 파일에는 프로젝트에 대한 메타 데이터가 포함되어 있습니다:
pyproject.toml
[project]
name = "hello-world"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
dependencies = [] |
이 파일은 종속성을 지정하고 프로젝트 설명이나 라이선스 같은 세부 정보를 기록하는 데 사용됩니다. 수동으로 편집하거나 uv add 및 uv remove 같은 명령어를 사용해 터미널에서 프로젝트를 관리할 수 있습니다.
pyproject.toml 포맷을 시작하는 방법에 대한 자세한 내용은 공식 pyproject.toml 가이드를 참조하십시오.
이 파일은 또한 [tool.uv] 섹션에서 uv 설정 옵션을 지정하는 데 사용됩니다.
.python-version
.python-version 파일에는 프로젝트의 기본 Python 버전이 포함됩니다. 이 파일은 uv가 프로젝트의 가상 환경을 생성할 때 사용할 Python 버전을 지정합니다.
.venv
.venv 폴더에는 프로젝트의 가상 환경이 포함되어 있습니다. 이는 시스템의 나머지 부분과 격리된 Python 환경입니다. uv가 프로젝트의 종속성을 설치하는 위치입니다.
uv.lock
uv.lock은 프로젝트의 종속성에 대한 정확한 정보를 포함하는 크로스 플랫폼 락파일(lockfile)입니다. 프로젝트의 광범위한 요구 사항을 지정하는 데 사용되는 pyproject.toml과 달리, 락파일에는 프로젝트 환경에 설치된 정확한 확인된 버전이 포함됩니다. 이 파일은 버전 관리에 체크인해야 하며, 이를 통해 여러 머신에서 일관되고 재현 가능한 설치를 가능하게 합니다.
uv.lock은 사람이 읽을 수 있는 TOML 파일이지만 uv에 의해 관리되므로 수동으로 편집해서는 안 됩니다.
