Windows, Ubuntu, macOS에서 uv를 설치하고 사용하는 방법을 다룹니다. uv는 Rust로 작성된 매우 빠른 Python 패키지 및 프로젝트 관리자입니다.
uv는 다양한 설치 방법을 제공하고 있습니다. 본 문서에서는 공식 설치 프로그램을 사용한 uv 설치 방법을 다룹니다.
.
2025.3.20 최초작성 . uv를 간단히 사용해봤습니다.
2025.9.4 업데이트
2026.8.14 업데이트. uv 0.12부터 uv init의 기본 프로젝트 구조가 변경되어 전체 내용을 다시 작성했습니다.
기존 프로젝트 방식을따라 진행하도록 수정했습니다.
.
이해를 돕기위해 영상으로도 제작했습니다.
.
1. uv 설치
macOS, Ubuntu
터미널에서 다음 명령을 실행합니다. 우분투의 경우엔 다음 단계를 진행하기전에 환경을 적용하기 위해 터미널을 다시 열어줘야 합니다. 실행과정이 동일하기 때문에 macOS의 실행결과만 남겨둡니다.
| curl -LsSf https://astral.sh/uv/install.sh | sh |
.
| webnautes@webnautesui-MacBookAir ~ % curl -LsSf https://astral.sh/uv/install.sh | sh downloading uv 0.12.4 aarch64-apple-darwin installing to /Users/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.12.4 (x86_64-pc-windows-msvc)installing to C:\Users\freem\.local\bin uv.exe uvx.exe uvw.exeeverything's installed! |
.
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 프로젝트이름 --python 파이썬버전 --no-package |
.
uv 0.12(2026.7.28 릴리즈)부터 uv init의 기본 동작이 변경되었습니다. 이전에는 프로젝트 루트에 main.py 파일을 생성하는 단순한 구조였지만, 이제는 src/프로젝트이름/ 디렉토리에 소스 코드를 두는 패키지형 구조가 기본으로
생성됩니다. pyproject.toml에는 uv 자체 빌드 백엔드인 uv_build를 사용하는
[build-system] 항목과 실행 명령을 정의하는 [project.scripts] 항목이 추가됩니다.
.
본 문서에서는 이전 방식의 단순한 구조(루트에 main.py)를 사용하기 위해 --no-package 옵션을 추가하여 진행합니다.
.
Windows
파이썬 3.13을 사용하도록 myproject 디렉토리에 프로젝트를 생성합니다.
| uv init myproject --python 3.13 --no-package |
| C:\Users\freem>uv init myproject --python 3.13 --no-package Initialized project `myproject` at `C:\Users\freem\myproject` |
.
생성된 디렉토리 내에 파일들이 생성됩니다.
| C:\Users\freem>dir myproject C 드라이브의 볼륨에는 이름이 없습니다. 볼륨 일련 번호: 9651-526A C:\Users\freem\myproject 디렉터리 2026-08-14 오후 03:10 <DIR> .2026-08-14 오후 03:10 <DIR> ..2026-08-14 오후 03:10 109 .gitignore2026-08-14 오후 03:10 5 .python-version2026-08-14 오후 03:10 87 main.py2026-08-14 오후 03:10 155 pyproject.toml2026-08-14 오후 03:10 0 README.md 5개 파일 356 바이트 |
.
다음처럼 파이썬을 설치할 수 있습니다.
| 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> |
.
macOS, Ubuntu
파이썬 3.13을 사용하도록 myproject 디렉토리에 프로젝트를 생성합니다. 실행과정이 동일하기 때문에 macOS의 실행결과만 남겨둡니다.
| uv init myproject --python 3.13 --no-package |
| webnautes@webnautesui-MacBookAir ~ % uv init myproject --python 3.13 --no-package Initialized project `myproject` at `/Users/webnautes/myproject` |
.
생성된 디렉토리 내에 파일들이 생성됩니다.
| webnautes@webnautesui-MacBookAir ~ % ls -al myproject total 24 drwxr-xr-x 8 webnautes staff 256 8월 14 12:38 . drwxr-xr-x+ 88 webnautes staff 2816 8월 14 12:38 .. drwxr-xr-x 9 webnautes staff 288 8월 14 12:38 .git -rw-r--r-- 1 webnautes staff 109 8월 14 12:38 .gitignore -rw-r--r-- 1 webnautes staff 5 8월 14 12:38 .python-version -rw-r--r-- 1 webnautes staff 357 8월 14 12:38 pyproject.toml -rw-r--r-- 1 webnautes staff 0 8월 14 12:38 README.md drwxr-xr-x 3 webnautes staff 96 8월 14 12:38 src |
.
참고로 다음처럼 원하는 디렉터리에서 프로젝트를 초기화할 수도 있습니다:
| mkdir hello-world cd hello-world uv init --python 3.13 --no-package |
.
3. 가상환경 생성
가상 환경을 생성합니다.
| uv venv |
.
앞에서 생성한 프로젝트 폴더로 이동하여 가상환경을 생성해야 합니다. 프로젝트 생성시 지정한 파이썬이 다운로드된후 가상환경이 생성됩니다. 해당 폴더에 .venv 폴더가 생성됩니다. 가상환경을 다시 생성하고 싶으면 .venv 폴더를 제거하면 됩니다.
.
Windows
| C:\Users\freem>cd myproject C:\Users\freem\myproject>uv venvUsing CPython 3.13.15Creating virtual environment at: .venvActivate with: .venv\Scripts\activate |
macOS / Ubuntu
실행과정이 동일하기 때문에 macOS의 실행결과만 남겨둡니다.
| webnautes@webnautesui-MacBookAir ~ % cd myproject webnautes@webnautesui-MacBookAir myproject % uv venv Using CPython 3.13.15 Creating virtual environment at: .venv Activate with: source .venv/bin/activate |
.
4. 가상환경 활성화
가상환경을 활성화합니다. 프롬프트 맨 앞에 폴더 이름이 붙습니다..
Windows
| .venv\Scripts\activate |
| C:\Users\freem\myproject>.venv\Scripts\activate 실행후 화면이 지워지고 아래 프롬프트만 표시됩니다. (myproject) C:\Users\freem\myproject> |
.
macOS / Ubuntu
| source .venv/bin/activate |
실행과정이 동일하기 때문에 macOS의 실행결과만 남겨둡니다.
| webnautes@webnautesui-MacBookAir myproject % source .venv/bin/activate (myproject) webnautes@webnautesui-MacBookAir myproject % |
.
5.패키지 설치
5번부터는 공통적인 내용이라 macOS에서 진행한 내용만 남겨둡니다.
프로젝트에 패키지를 추가하려면 다음 명령어를 사용합니다:
| uv add 패키지명 |
.
opencv-python 패키지를 설치합니다.
| (myproject) webnautes@webnautesui-MacBookAir myproject % uv add opencv-python Resolved 3 packages in 349ms Prepared 2 packages in 5.16s Installed 2 packages in 25ms + numpy==2.5.2 + opencv-python==5.0.0.93 |
.
설치된 패키지 목록을 확인합니다.
| (myproject) webnautes@webnautesui-MacBookAir myproject % uv pip list Package Version ------------- -------- numpy 2.5.2 opencv-python 5.0.0.93 |
.
pyproject.toml 파일에서도 확인이 가능합니다. 같이 설치되었던 numpy는 기록되어 있지 않습니다.
| (myproject) webnautes@webnautesui-MacBookAir myproject % cat pyproject.toml [project]name = "myproject"version = "0.1.0"description = "Add your description here"readme = "README.md"requires-python = ">=3.13"dependencies = [ "opencv-python>=5.0.0.93",] |
.
대안으로 다음 명령을 사용하여 패키지를 설치할 수도 있습니다.
| uv pip install 패키지명 |
.
설치할 버전 제약 조건을 지정하거나 다른 출처를 지정할 수도 있습니다:
| # 설치할 패키지의 버전을 지정합니다. uv add 'requests==2.31.0' # 패키지를 설치할 때 사용할 주소를 지정합니다. uv add git+https://github.com/psf/requests |
.
6. 파이썬 코드 실행
프로젝트 생성시 현재 디렉토리에 main.py 파일이 생성되어 있습니다. 파이썬 코드를 실행합니다.
| uv run main.py |
| (myproject) webnautes@webnautesui-MacBookAir myproject % uv run main.py Hello from myproject! |
.
main.py 파일을 다음처럼 수정합니다. OpenCV 라이브러리의 버전을 출력하도록 합니다.
| import cv2 print(cv2.__version__) |
.
다시 실행해봅니다.
| (myproject) webnautes@webnautesui-MacBookAir myproject % uv run main.py 5.0.0 |
.
참고로 --no-package 옵션 없이 생성한 기본 패키지형 프로젝트에서는 src\프로젝트이름_init_.py에 main 함수가 생성되며, uv run 프로젝트이름 명령으로 실행합니다.
.
7. 패키지 제거
패키지를 제거합니다.
| uv remove 패키지명 |
opencv-python 패키지를 제거해봅니다.
| (myproject) webnautes@webnautesui-MacBookAir myproject % uv remove opencv-python Resolved 1 package in 15ms Uninstalled 2 packages in 77ms - numpy==2.5.2 - opencv-python==5.0.0.93 |
.
대안으로 다음 명령을 사용하여 패키지를 삭제할 수도 있습니다.
| uv pip uninstall 패키지명 |
.
8.가상환경 비활성화
가상환경을 비활성화 합니다.
| deactivate |
.
프롬프트앞에 붙어있던 프로젝트 디렉토리 이름이 사라집니다.
| (myproject) webnautes@webnautesui-MacBookAir myproject % deactivate webnautes@webnautesui-MacBookAir myproject % |
.
파이썬 스크립트에 인수를 제공할 수 있습니다:
main.py를 다음처럼 수정합니다.
| import sys print(" ".join(sys.argv[1:])) |
.
실행해봅니다. 받은 인수를 출력해줍니다.
| webnautes@webnautesui-MacBookAir myproject % uv run main.py test test |
.
프로젝트 구조
프로젝트는 uv가 프로젝트를 관리할 수 있게 하는 몇 가지 중요한 부분으로 구성됩니다. uv init으로 생성된 파일 외에도, uv는 프로젝트 명령어(예: uv run, uv sync, uv lock)를 처음 실행할 때 프로젝트 루트에 가상 환경과 uv.lock 파일을 생성합니다.
.
--no-package 옵션으로 생성한 프로젝트의 전체 구조는 다음과 같습니다
.
참고로 uv 0.12부터 기본으로 생성되는 패키지형 프로젝트는 main.py 대신 src/프로젝트이름/init.py에 소스 코드가 위치하며, pyproject.toml에 [build-system]과 [project.scripts] 항목이 추가됩니다.
.
pyproject.toml
pyproject.toml 파일에는 프로젝트에 대한 메타 데이터가 포함되어 있습니다:
pyproject.toml
| [project]name = "myproject"version = "0.1.0"description = "Add your description here"readme = "README.md"requires-python = ">=3.13"dependencies = [] |
.
이 파일은 종속성을 지정하고 프로젝트 설명이나 라이선스 같은 세부 정보를 기록하는 데 사용됩니다. 수동으로 편집하거나 uv add 및 uv remove 같은 명령어를 사용해 터미널에서 프로젝트를 관리할 수 있습니다.
pyproject.toml 포맷을 시작하는 방법에 대한 자세한 내용은 공식 pyproject.toml 가이드를 참조하십시오.
이 파일은 또한 [tool.uv] 섹션에서 uv 설정 옵션을 지정하는 데 사용됩니다.
.
.python-version
.python-version 파일에는 프로젝트의 기본 Python 버전이 포함됩니다. 이 파일은 uv가 프로젝트의 가상 환경을 생성할 때 사용할 Python 버전을 지정합니다.
| webnautes@webnautesui-MacBookAir myproject % cat .python-version 3.13 |
.
.venv
.venv 폴더에는 프로젝트의 가상 환경이 포함되어 있습니다. 이는 시스템의 나머지 부분과 격리된 Python 환경입니다. uv가 프로젝트의 종속성을 설치하는 위치입니다.
.
uv.lock
uv.lock은 프로젝트의 종속성에 대한 정확한 정보를 포함하는 크로스 플랫폼 락파일(lockfile)입니다. 프로젝트의 광범위한 요구 사항을 지정하는 데 사용되는 pyproject.toml과 달리, 락파일에는 프로젝트 환경에 설치된 정확한 확인된 버전이 포함됩니다. 이 파일은 버전 관리에 체크인해야 하며, 이를 통해 여러 머신에서 일관되고 재현 가능한 설치를 가능하게 합니다.
uv.lock은 사람이 읽을 수 있는 TOML 파일이지만 uv에 의해 관리되므로 수동으로 편집해서는 안 됩니다.
.