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

uv چیست و چرا برنامه‌نویسان پایتون به آن روی آورده‌اند؟

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

چرا pip و venv دیگر کافی نیستند؟

سال‌هاست جریان کار استاندارد پایتون این است: اول یک محیط مجازی با python -m venv .venv می‌سازی، بعد آن را فعال می‌کنی و بعد پکیج‌ها را با pip install نصب می‌کنی. این جریان کار می‌کند، اما در دنیای امروز که پروژه‌ها ده‌ها وابستگی دارند، مشکلاتش خودشان را نشان می‌دهند:

سرعت پایین: pip برای نصب هر پکیج باید وابستگی‌های آن را یکی‌یکی بررسی و دانلود کند؛ در پروژه‌های بزرگ این کار می‌تواند چند دقیقه طول بکشد.
فعال‌سازی محیط مجازی: هر بار باید یادت باشد محیط مجازی را فعال کنی وگرنه پکیج‌ها در پایتون اصلی نصب می‌شوند و همه‌چیز به‌هم می‌ریزد.
ناسازگاری نسخه‌ها: requirements.txt معمولاً نسخه دقیق پکیج‌ها را مشخص نمی‌کند؛ برای همین روی سیستم دو نفر از تیم، برنامه رفتار متفاوتی دارد.
ابزارهای پراکنده: برای کارهای مختلف باید pip، virtualenv، pip-tools و گاهی pyenv را جداگانه یاد بگیری و نگهداری کنی.

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

uv چه کارهایی انجام می‌دهد؟

uv یک باینری واحد است که چند ابزار پراکنده را در خودش جمع کرده است:

جایگزین pip: نصب، حذف و به‌روزرسانی پکیج‌ها با سرعتی چند برابر pip.
جایگزین virtualenv: ساخت و مدیریت خودکار محیط مجازی؛ دیگر لازم نیست آن را دستی فعال کنی.
جایگزین pyenv: نصب و تغییر نسخه پایتون با چند دستور ساده.
uvx: اجرای ابزارهای پایتونی بدون نصب دائمی آن‌ها (مثل pipx).
فایل قفل uv.lock: ثبت دقیق نسخه همه پکیج‌ها برای اجرای یکسان روی هر سیستم.

در جدول زیر ببینید هر کاری که قبلاً با دو سه ابزار انجام می‌دادید، حالا با uv چطور می‌شود:

ویژگی	pip + venv	uv
نصب پکیج	pip install	uv add (تا ۱۰ برابر سریع‌تر)
محیط مجازی	python -m venv + فعال‌سازی دستی	ساخت خودکار با uv
مدیریت نسخه پایتون	نیاز به pyenv یا نصب دستی	uv python install
ثبت نسخه پکیج‌ها	requirements.txt (ناقص)	uv.lock (دقیق و کامل)
تعداد ابزارهای لازم	۳ تا ۴ ابزار جداگانه	فقط uv

نصب uv

خبر خوب این است که uv یک فایل اجرایی مستقل است و به پایتون نصب‌شده روی سیستم هم وابسته نیست. نصب آن در هر سیستم‌عامل فقط یک دستور است.

نصب uv روی ویندوز

در PowerShell (ترمینال ویندوز) این دستور را اجرا کن:

irm https://astral.sh/uv/install.ps1 | iex

نصب uv روی macOS و لینوکس

در ترمینال این دستور را اجرا کن:

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

بعد از نصب، با این دستور مطمئن شو همه‌چیز درست است:

uv --version

نکته: اگر بعد از نصب، سیستم گفت دستور uv شناخته نمی‌شود، ترمینال را ببند و دوباره باز کن تا مسیر نصب در PATH بارگذاری شود.

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

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

uv init hello-uv
cd hello-uv

حالا یک پکیج به پروژه اضافه کن، مثلاً کتابخانه requests:

uv add requests

و کد پروژه را اجرا کن:

uv run python main.py

در همین سه قدم، uv فایل‌های پروژه را ساخته، محیط مجازی را به‌صورت خودکار ایجاد کرده، requests را نصب کرده و کد را داخل همان محیط مجازی اجرا کرده است — بدون اینکه حتی یک بار یادت بیفتد .venv را فعال کنی. فایل‌های pyproject.toml و uv.lock هم برایت ساخته شده‌اند تا نسخه دقیق پکیج‌ها ثبت شود.

مدیریت پکیج‌ها در پروژه‌های موجود

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

ساخت محیط مجازی: uv venv
نصب از requirements.txt: uv pip install -r requirements.txt
همگام‌سازی با فایل قفل: uv sync

جدول زیر معادل دستورهای آشنای pip را در uv نشان می‌دهد:

کاری که می‌خواهی	دستور pip/venv	دستور uv
نصب پکیج	pip install requests	uv add requests
ساخت محیط مجازی	python -m venv .venv	uv venv
نصب همه وابستگی‌ها	pip install -r requirements.txt	uv pip install -r requirements.txt
مشاهده پکیج‌های نصب‌شده	pip freeze	uv pip freeze
حذف پکیج	pip uninstall requests	uv remove requests

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

یکی از قابلیت‌هایی که uv را خاص می‌کند، مدیریت خودِ پایتون است. دیگر لازم نیست پایتون را از سایت دانلود کنی یا pyenv نصب کنی؛ با uv می‌شود:

uv python install 3.12 # نصب نسخه دلخواه پایتون
uv python pin 3.12 # تعیین نسخه برای پروژه فعلی
uv run --python 3.12 main.py # اجرای کد با نسخه مشخص

این یعنی روی یک سیستم می‌توانی چند نسخه پایتون داشته باشی و برای هر پروژه نسخه دلخواه خودت را انتخاب کنی؛ بدون هیچ تداخلی.

اجرای ابزارهای یک‌بارمصرف با uvx

گاهی فقط می‌خواهی یک ابزار پایتونی را یک بار اجرا کنی، مثلاً یک lint بگیری یا یک فایل را تبدیل کنی؛ نه نیازی به نصب دائمی داری و نه می‌خواهی سیستم را کثیف کنی. uvx این کار را انجام می‌دهد:

uvx ruff check .

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

نکات حرفه‌ای و مشکلات رایج

کش uv: پکیج‌های دانلودشده در کش نگهداری می‌شوند تا نصب‌های بعدی تقریباً آنی باشد. اگر فضای دیسک کم آوردی، با uv cache clean کش را پاک کن.
کار آفلاین: اگر اینترنت محدودی داری، با uv sync --offline از کش برای همگام‌سازی استفاده کن.
خطای شناخته‌نشدن uv در ویندوز: ترمینال را دوباره باز کن؛ اگر باز هم خطا دیدی، مسیر %USERPROFILE%\.local\bin را دستی به PATH اضافه کن.
استفاده در CI/CD: در گیت‌هاب اکشنز به‌جای نصب دستی، از اکشن رسمی astral-sh/setup-uv استفاده کن تا uv در چند ثانیه آماده شود.
اجرای پروژه در محیط ایزوله: وقتی پروژه‌ات بزرگ‌تر شد و خواستی آن را در محیطی کاملاً ایزوله و قابل‌حمل اجرا کنی، آموزش داکر را ببین؛ uv و داکر مکمل خوبی برای هم هستند.

جمع‌بندی

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

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

آیا uv جایگزین کامل pip است؟

بله. uv برای نصب، حذف و به‌روزرسانی پکیج‌ها جایگزین کامل pip است و در بیشتر موارد چند برابر سریع‌تر عمل می‌کند. دستورهای pip هم برای پروژه‌های قدیمی پشتیبانی می‌شوند (uv pip install) تا مهاجرت نرم باشد.

تفاوت uv و Poetry چیست؟

هر دو مدیریت پروژه و فایل قفل دارند، اما uv با زبان Rust نوشته شده و سرعت بسیار بالاتری دارد. علاوه بر این uv ابزارهای بیشتری مثل مدیریت نسخه پایتون و uvx را در یک باینری ارائه می‌دهد، در حالی که Poetry تمرکز بیشتری روی بسته‌بندی و انتشار پکیج دارد.

می‌توانم uv را در پروژه‌های قدیمی استفاده کنم؟

بله. با دستورهای uv venv و uv pip install -r requirements.txt می‌توانی بدون تغییر ساختار پروژه، از مزیت سرعت uv استفاده کنی و بعداً به‌تدریج به pyproject.toml و uv.lock مهاجرت کنی.

آموزش uv در پایتون؛ نصب، ساخت محیط مجازی و مدیریت پکیج‌ها با uv