راهنمای جامع ابزار uv

اگر چند سالی است که با پایتون کار می‌کنید، احتمالاً با ابزارها و اصطلاحاتی مانند pip ، venv و virtualenv یا حتی Poetry سروکار داشته‌اید. هرکدام از این ابزارها بخشی از فرآیند مدیریت پروژه را بر عهده دارند؛ یکی بسته‌ها را نصب می‌کند، دیگری محیط مجازی می‌سازد و ابزار دیگری وابستگی‌ها را مدیریت می‌کند. اما در سال‌های اخیر، ابزار uv در پایتون معرفی شده که هدف آن ساده‌سازی تمام این فرآیندها است. uv علاوه بر اینکه سرعت بسیار بالایی دارد، می‌تواند تقریباً تمام وظایف ابزارهای بالا را به تنهایی انجام دهد؛ از نصب پکیج‌ها گرفته تا مدیریت نسخه‌های مختلف پایتون، ساخت محیط مجازی، مدیریت وابستگی‌ها، اجرای اسکریپت‌ها و حتی نصب ابزارهای خط فرمان.

اگر قصد دارید پروژه‌های جدید پایتون را با روشی مدرن‌تر مدیریت کنید، احتمالاً uv بهترین انتخاب شما خواهد بود. در این مقاله به صورت کامل با uv آشنا می‌شویم، روش نصب آن را بررسی می‌کنیم، مهم‌ترین دستورات آن را یاد می‌گیریم، آن را با pip و venv مقایسه می‌کنیم و در پایان به رایج‌ترین سوالات احتمالی شما پاسخ داده می‌شود.

ابزار uv چیست؟

ابزار uv یک ابزار متن‌باز است که توسط شرکت Astral توسعه داده شده و با زبان Rust نوشته شده است. هدف اصلی ابزار uv این است که به جای استفاده از چندین ابزار مختلف، تنها با یک برنامه بتوانید:

• مدیریت پکیج‌های پایتون
• ساخت محیط مجازی
• مدیریت نسخه‌های پایتون
• مدیریت وابستگی‌های پروژه
• ایجاد Lock File
• اجرای اسکریپت‌ها
• نصب ابزارهای CLI

را انجام دهید.

یکی از مهم‌ترین ویژگی‌های uv، سرعت فوق‌العاده آن است. در بسیاری از پروژه‌ها، نصب وابستگی‌ها بین ۱۰ تا ۱۰۰ برابر سریع‌تر از pip انجام می‌شود؛ زیرا uv از دانلودهای موازی، کش هوشمند و الگوریتم‌های بهینه برای ریزالو کردن وابستگی‌ها استفاده می‌کند.

چرا uv محبوب شده است؟

دلایل محبوبیت uv عبارتند از:

• سرعت بسیار بالا
• جایگزین مناسب برای pip و venv
• مدیریت خودکار محیط مجازی
• مدیریت نسخه‌های مختلف پایتون
• فایل Lock برای نصب دقیق وابستگی‌ها
• سازگاری با استانداردهای رسمی پایتون
• امکان مهاجرت آسان از پروژه‌های قدیمی
• نصب سریع ابزارهای CLI بدون آلوده کردن سیستم

نصب ابزار uv

نصب در لینوکس و WSL

نصب ابزار uv در لینوکس و WSL بسیار ساده است و تنها با وارد کردن یک خط کد در ترمینال لینوکس انجام می‌شود:

curl -LsSf https://astral.sh/uv/install.sh | sh

نصب در ویندوز

برای نصب uv در ویندوز، ابتدا پاورشل ویندوز را اجرا کرده و دستور زیر را وارد کنید:

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

البته می‌توانید با استفاده از Winget نیز، ابزار uv را در ویندوز نصب کنید:

winget install --id=astral-sh.uv -e

پس از نصب، نسخه uv خود را بررسی کنید:

uv --version

ساخت اولیه پروژه با uv

ساخت پروژه جدید بسیار ساده است و پس از ورود به پوشه مدنظر، کافیست دستور init را وارد کنید:

mkdir myproject
cd myproject

uv init

با همین دستور فایل‌های زیر ایجاد می‌شوند که در ادامه به کاربردهای هر کدام پرداخته خواهد شد:

pyproject.toml
uv.lock
.python-version
.venv/

نصب پکیج با uv

به جای دستور معروف install که در pip استفاده می‌کردید، در uv تنها کافی است دستور add را بنویسید:

uv add requests

با اجرای این دستور، همزمان:

• پکیج مدنظر نصب می‌شود.
• فایل pyproject.toml به‌روزرسانی می‌شود.
• فایل uv.lock ساخته می‌شود.
• محیط مجازی Sync می‌شود.

اجرای برنامه پایتونی با uv

هنگامی که شما از محیط مجازی استفاده می‌کردید، ابتدا می‌بایست محیط مجازی را فعال و سپس فایل پایتونی مدنظر را اجرا می‌کردید:

source .venv/bin/activate
python app.py

با استفاده از ابزار uv در پایتون، تنها کافی است بنویسید:

uv run python app.py

یا مثلاً برای اجرای سرور جنگو کافیست بنویسید:

uv run python manage.py runserver

در اکثر مواقع، دیگر نیازی به ساختن و فعال کردن محیط مجازی نخواهید داشت!

مهم‌ترین دستورهای ابزار uv

در جدول زیر، پرکاربردترین دستورهای ابزار uv در پایتون گردآوری شده‌اند:

تفاوت uv با سایر ابزارها

الف) تفاوت uv با pip

ابزار pip در پایتون، پکیج منیجر رسمی زبان برنامه‌نویسی پایتون برای نصب کتابخانه‌ها و ماژول‌ها است و به صورت پیش‌فرض همراه بسیاری از نسخه‌های پایتون نصب می‌شود. نصب پکیج‌ها و وابستگی‌ها، حذف یا آپدیت کتابخانه‌ها، نصب یک نسخه مشخص از یک پکیج، مدیریت دسته جمعی وابستگی‌ها با استفاده از requirements.txt شاید از مهمترین کاربردهای ابزار pip در پایتون باشد.

ب) تفاوت uv با venv

ماژول venv در پایتون تنها یک وظیفه دارد و آن ساخت محیط مجازی (Virtual Environment) است. اما ابزار uv علاوه بر ساخت محیط مجازی، می‌تواند مدیریت و نصب وابستگی‌ها، مدیریت و نصب نسخه پایتون، اجرای پروژه و همگام‌سازی (sync) آن را نیز برای شما انجام دهد.

ج) تفاوت uv با Poetry

Poetry سال‌ها یکی از محبوب‌ترین ابزارهای مدیریت پروژه و وابستگی‌های پایتون است که با هدف ساده‌سازی فرآیند توسعه معرفی شد. این ابزار امکاناتی مانند مدیریت وابستگی‌ها، ایجاد و مدیریت محیط مجازی، ساخت فایل Lock برای نصب تکرارپذیر وابستگی‌ها، ایجاد پروژه‌های جدید، ساخت بسته‌های قابل انتشار (Wheel و Source Distribution) و انتشار مستقیم آن‌ها در PyPI را در یک محیط یکپارچه فراهم می‌کند.

ابزار Poetry نیز مانند uv از فایل استاندارد pyproject.toml برای نگهداری اطلاعات پروژه و وابستگی‌ها استفاده می‌کند و به همین دلیل مهاجرت بین این دو ابزار نسبتاً ساده است.

با وجود اینکه Poetry سال‌ها به عنوان یکی از بهترین ابزارهای مدیریت پروژه‌های پایتون شناخته می‌شد و هنوز هم در بسیاری از پروژه‌های متن‌باز و سازمانی استفاده می‌شود، اما در سال‌های اخیر ابزار uv به دلیل سرعت بسیار بالاتر، مدیریت داخلی نسخه‌های مختلف پایتون، سازگاری بیشتر با اکوسیستم pip و قابلیت‌هایی مانند uv run، uv tool و uvx به گزینه محبوب‌تری برای پروژه‌های جدید تبدیل شده است. با این حال، اگر قصد توسعه و انتشار کتابخانه‌های پایتون در PyPI را دارید یا روی پروژه‌هایی کار می‌کنید که از قبل بر پایه Poetry ساخته شده‌اند، یادگیری و استفاده از آن همچنان ارزشمند خواهد بود.

مهاجرت به uv

اگر پروژه قدیمی دارید که نیازمندی‌های خود را با فایل requirements.txt مشخص کرده، می‌توانید آن را به uv مهاجرت دهید:

uv init
uv add -r requirements.txt
uv sync

پس از بررسی صحت اجرای پروژه، بهتر است مدیریت وابستگی‌ها را کاملاً به uv بسپارید.

چه زمانی هنوز از pip استفاده کنیم؟

با وجود قابلیت‌های فراوان ابزار uv، هنوز در برخی شرایط استفاده از pip منطقی است:

• پروژه‌های بسیار قدیمی
• سرورهایی که امکان نصب uv ندارند
• برخی سیستم‌های CI قدیمی
• محیط‌هایی که فقط requirements.txt را می‌پذیرند

البته حتی در این شرایط نیز می‌توانید فایل requirements.txt را از روی uv تولید کنید. بنابراین اگر تمایل دارید از وابستگی‌های پروژه uv خود یک خروجی requirements.txt تهیه کنید، کافیست دستور زیر را وارد کنید:

uv export --format requirements-txt > requirements.txt

از آنجایی که ابزار uv وابستگی‌های عادی و حالت توسعه را از هم جدا می‌کند، چنانچه نمی‌خواهید پکیج‌های حالت توسعه را برای محیط پروداکشن خروجی بگیرید، دستور زیر را وارد کنید:

uv export --format requirements-txt --no-dev > requirements.txt

این روش به‌خصوص برای هاستینگ‌هایی با پنل قدیمی، ایمیج‌های داکر و یا سرویس‌هایی که از uv.lock پشتیبانی نمی‌کنند، مفید است.

ساختار پروژه‌های مبتنی بر uv

یک پروژه استاندارد که با ابزار uv در پایتون ساخته شده، معمولاً به شکل زیر است:

project/
├── pyproject.toml
├── uv.lock
├── .python-version
├── .venv/
├── src/
└── README.md

یکی از مهم‌ترین تفاوت‌های ابزار uv با ابزارهای قدیمی مانند pip و venv، استفاده از چند فایل استاندارد برای مدیریت پروژه است. این فایل‌ها باعث می‌شوند وابستگی‌ها، نسخه پایتون و تنظیمات پروژه به صورت دقیق ثبت شوند تا تمام اعضای تیم، سرورهای CI/CD و محیط‌های پروداکشن، دقیقاً از یک پیکربندی استفاده کنند.

الف) فایل pyproject.toml

فایل pyproject.toml مهم‌ترین فایل هر پروژه مدرن پایتون محسوب می‌شود. این فایل مطابق استاندارد PEP-518 و PEP-621 طراحی شده و تقریباً تمام ابزارهای جدید پایتون از آن پشتیبانی می‌کنند. به زبان ساده، این فایل مشخص می‌کند:

• نام پروژه چیست؟
• نسخه پروژه چیست؟
• حداقل نسخه پایتون موردنیاز چند است؟
• وابستگی‌های اصلی پروژه چه هستند؟
• وابستگی‌های حالت توسعه (Development) چه هستند؟
• در صورت نیاز، تنظیمات ابزارهایی مانند Ruff و Pytest و سایر ابزارها را تعیین می‌کند.

مدیریت وابستگی‌ها: نکته مهم این است که برخلاف pip و فایل requirements.txt، تنها وابستگی‌هایی که شما مستقیماً انتخاب می‌کنید در این فایل ثبت می‌شوند و وابستگی‌های غیرمستقیم در این فایل قرار نمی‌گیرند. نمونه ساده زیر را ببینید:

[project]
name = "myproject"
version = "0.1.0"
description = "My Django Project"
readme = "README.md"
requires-python = ">=3.12,<3.14"

dependencies = [
	"django>=5.2",
	"requests>=2.32"
]

[dependency-groups]
dev = [
	"pytest >=8.1.1,<9",
	"ruff>=0.13"
]

در این مثال، فقط دو پکیج Django و Requests توسط توسعه‌دهنده انتخاب شده‌اند؛ اما هنگام نصب، چندین پکیج دیگر نیز به عنوان وابستگی نصب خواهند شد که در این فایل دیده نمی‌شوند.

وابستگی‌های حالت توسعه: معمولاً ابزارهایی مانند Ruff یا Pytest که فقط هنگام توسعه استفاده می‌شوند، نباید به عنوان وابستگی اصلی پروژه نصب شوند. برای همین، قسمت مجزایی تحت عنوان dependency-groups برای آنها در نظر گرفته شده است.

تعیین نسخه پایتون: یکی از مهم‌ترین بخش‌های فایل pyproject.toml تعیین نسخه پایتون سازگار پروژه است. مثلاً در مثال ساده بالا، توسعه‌دهنده مشخص کرده که این پروژه فقط با نسخه‌های 3.12 و 3.13 سازگار است و روی نسخه 3.14 یا 3.11 اجرا نخواهد شد.

تنظیمات ابزارهای دیگر: مزیت بزرگ فایل pyproject.toml این است که بسیاری از ابزارهای اکوسیستم پایتون تنظیمات خود را نیز در همین فایل ذخیره می‌کنند و دیگر نیازی به فایل‌های جداگانه نیست. به عنوان مثال، می‌توانید برای ابزار لینتر ruff مشخص کنید که حداکثر طول خطوط چقدر باشد یا به ابزار pytest بگویید که تست‌های شما در کجا نوشته شده‌اند:

[tool.ruff]
line-length = 100

[tool.pytest.ini_options]
testpaths = ["tests"]

ب) فایل uv.lock

اگر فایل pyproject.toml مشخص می‌کند چه چیزهایی می‌خواهیم، فایل uv.lock مشخص می‌کند که دقیقاً چه چیزهایی نصب شده‌ است. مثلاً فرض کنید شما دستور زیر را اجرا کرده‌اید:

در فایل pyproject.toml فقط Django به عنوان وابستگی پروژه ثبت می‌شود. اما هنگام نصب، uv ممکن است چندین وابستگی دیگر مانند asgiref و sqlparse و tzdata را نیز نصب کند. تمام این وابستگی‌ها به همراه نسخه دقیق، منبع دانلود و اطلاعات لازم برای نصب مجدد در فایل uv.lock ذخیره می‌شوند.

چرا فایل uv.lock برای ما مهم است؟ فرض کنید امروز پروژه را آغاز می‌کنید. شش ماه بعد یکی از وابستگی‌های Django نسخه جدیدی منتشر می‌کند. اگر فقط فایل pyproject.toml را داشته باشید، ممکن است هنگام نصب، نسخه متفاوتی دریافت کنید و پروژه رفتار دیگری داشته باشد. اما اگر فایل uv.lock وجود داشته باشد، تمام افراد تیم، همیشه دقیقاً همان نسخه‌هایی را نصب خواهند کرد که قبلاً تست شده‌اند.

ج) فایل python-version.

این فایل بسیار کوچک است اما نقش مهمی در یکپارچگی پروژه دارد زیرا مشخص می‌کند پروژه باید با کدام نسخه پایتون اجرا شود. اگر چند نسخه مختلف پایتون روی سیستم نصب کرده باشید، uv هنگام اجرای پروژه، این فایل را بررسی کرده و نسخه مناسب را انتخاب می‌کند.

شاید بپرسید مگر نسخه موردنیاز پایتون را فایل pyproject.toml مشخص نکردیم؟ معمولاً این سوال برای کاربران پیش می‌آید. باید دقت داشت که قسمت requires-python فایل pyproject.toml مشخص می‌کند پروژه با چه نسخه‌هایی سازگار است. اما فایل python-version. تنها مشخص می‌کند هنگام اجرای پروژه، کدام نسخه نصب‌شده روی سیستم استفاده شود.

سوالات متداول

ابزار uv در پایتون را می‌توان نسل جدید ابزارهای مدیریت پروژه‌های پایتون دانست. این ابزار نه تنها جایگزین مناسبی برای pip و venv محسوب می‌شود، بلکه بسیاری از قابلیت‌های Poetry و pip-tools و pipx را نیز در خود جای داده است. اگر به تازگی وارد دنیای پایتون شده‌اید یا قصد دارید پروژه‌های جدیدی را آغاز کنید، یادگیری uv می‌تواند باعث ساده‌تر شدن فرآیند توسعه، افزایش سرعت نصب وابستگی‌ها و مدیریت بهتر پروژه‌ها شود.