اگر نصب هر وابستگی پایتون برای پروژه‌های هوش مصنوعی‌تان دقیقه‌ها طول می‌کشد، محیط‌های مجازی به‌هم می‌ریزد و pip و Poetry هرکدام نیمی از کار را می‌کنند، وقتش است uv را بشناسید. uv ابزار یکپارچه Astral (سازنده Ruff) به زبان Rust است که ساخت محیط، نصب بسته، قفل وابستگی، اجرای اسکریپت و مدیریت ابزارها را تا ده‌ها برابر سریع‌تر و با یک دستور واحد انجام می‌دهد. در ادامه نصب، ساخت venv، مدیریت وابستگی، uv run و مهاجرت از pip/Poetry را گام‌به‌گام می‌بینید.

uv در پایتون چیست و چرا از pip سریع‌تر است؟

uv یک مدیر بسته و محیط پایتونِ همه‌کاره و فوق‌سریع است که جایگزین pip، pip-tools، virtualenv و بخشی از pyenv می‌شود؛ با Rust نوشته شده، کش هوشمند دارد و resolver آن وابستگی‌ها را در ثانیه حل می‌کند. برخلاف pip که هر بار همه چیز را از نو واکشی می‌کند، uv کش سراسری، نصب موازی و uv.lock دقیق دارد و هم برای اسکریپت تک‌فایلی و هم برای پروژه بزرگ با pyproject.toml یکسان کار می‌کند.

فهرست مطالب

پیش‌نیازها و نصب uv
اولین محیط مجازی با uv؛ از صفر تا اجرا
مدیریت وابستگی‌ها؛ add، remove، sync و قفل
اجرای بی‌دردسر اسکریپت‌ها؛ uv run، uvx و uv tool
مقایسه uv با pip، Poetry و pip-tools
کاربرد واقعی؛ راه‌اندازی پروژه AI با FastAPI و httpx
اشتباهات رایج هنگام کار با uv
سوالات متداول
جمع‌بندی

پیش‌نیازها و نصب uv

به پایتون ۳.۸+ نیاز دارید ولی uv خودش نسخه پایتون را هم می‌تواند نصب کند. روی ویندوز، مک و لینوکس یکسان است و بدون وابستگی سیستم نصب می‌شود.

# روش رسمی (ویندوز PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# مک / لینوکس
curl -LsSf https://astral.sh/uv/install.sh | sh

# با pipx یا pip (اگر قبلاً پایتون دارید)
pipx install uv
# یا
pip install uv

# بررسی نصب
uv --version
uv self update  # به‌روزرسانی uv خودش

ویرایشگر: VS Code با افزونه Python؛ uv خودکار مفسر را پیدا می‌کند و نیاز به فعال‌سازی دستی نیست.
کش: uv کش سراسری در ~/.cache/uv دارد؛ نصب دوم همان بسته حتی آفلاین و فوری است.
مدیریت پایتون: با uv python install 3.12 می‌توانید پایتون ۳.۱۲ را بدون pyenv نصب کنید.
نسخه پیشنهادی: uv نسخه 0.7 به بالا؛ با uv --version چک کنید.

اگر پروژه‌تان الان با Ruff تمیز می‌شود، uv مکمل طبیعی آن است— هر دو از Astral و با فلسفه «سریع و بی‌حاشیه». اگر Ruff را نمی‌شناسید، آموزش Ruff در پایتون را اول بخوانید تا پایپ‌لاین لینت و فرمت‌تان یکدست شود.

اولین محیط مجازی با uv؛ از صفر تا اجرا

ساده‌ترین سناریو: یک پوشه خالی، یک venv، نصب یک کتابخانه و اجرا— همه بدون python -m venv و بدون فعال‌سازی دستی.

mkdir ai-demo && cd ai-demo

# ساخت محیط مجازی (مثل python -m venv .venv اما سریع‌تر)
uv venv --python 3.12

# نصب یک بسته در محیط (بدون نیاز به activate)
uv pip install requests

# اجرای اسکریپت داخل همان محیط
uv run python -c "import requests; print(requests.__version__)"

توضیح خط‌به‌خط

uv venv: محیط مجازی .venv می‌سازد؛ --python 3.12 اگر ۳.۱۲ ندارید خودکار دانلود می‌کند.
uv pip install: سینتکس آشنا ولی با resolver و کش سریع؛ می‌توانید uv pip install -r requirements.txt هم بزنید.
uv run: دستور را داخل محیط پروژه اجرا می‌کند؛ نیازی به source .venv/bin/activate یا .venv\Scripts\activate نیست و خطای «مفسر اشتباه» حذف می‌شود.
بدون activate: uv مسیر venv را خودکار کشف می‌کند؛ اگر چند نسخه پایتون دارید، همیشه همان محیط پروژه استفاده می‌شود.

# تعریف پروژه رسمی با pyproject.toml (توصیه برای پروژه واقعی)
uv init --name ai-demo --python 3.12
# ساختار: pyproject.toml + README + hello.py + .python-version
cat pyproject.toml

خروجی uv init یک pyproject.toml تمیز با requires-python و وابستگی‌ها می‌سازد و پروژه را از «مجموعه اسکریپت» به «پکیج قابل نصب» تبدیل می‌کند.

مدیریت وابستگی‌ها؛ add، remove، sync و قفل

قلب uv در uv add / remove / sync / lock است. این دستورها pyproject.toml و uv.lock را هم‌زمان به‌روز می‌کنند و نصب را تکرارپذیر می‌کنند.

# افزودن وابستگی (مثل poetry add اما سریع)
uv add fastapi httpx

# افزودن وابستگی dev
uv add --dev pytest ruff

# افزودن با محدوده نسخه
uv add "pydantic>=2.9,<3"

# حذف
uv remove httpx

# قفل دقیق (uv.lock) بدون نصب
uv lock

# همگام‌سازی محیط با قفل (نصب تمیز روی سرور/هم‌تیمی)
uv sync

# همگام‌سازی شامل گروه dev
uv sync --dev

# دیدن درخت وابستگی
uv tree
uv pip list

uv.lock: فایل قفل دقیق با هش هر بسته؛ جایگزین poetry.lock و requirements.txt پین‌شده است.
uv sync: محیط را دقیقاً مطابق lock می‌سازد؛ بسته اضافی حذف و کمبود نصب می‌شود— ایده‌آل برای CI.
سازگاری pip: اگر هنوز requirements.txt دارید، uv pip compile requirements.in -o requirements.txt مثل pip-tools اما در میلی‌ثانیه.
افزودن از git: uv add git+https://github.com/org/repo.git پشتیبانی می‌شود.

برای پروژه‌های AI که torch یا transformers سنگین دارند، uv sync با کش و نصب موازی، زمان CI را از دقیقه به ثانیه می‌آورد.

اجرای بی‌دردسر اسکریپت‌ها؛ uv run، uvx و uv tool

uv فقط نصب نیست؛ اجرای اسکریپت تک‌فایلی با وابستگی درونی و اجرای ابزارهای یک‌بارمصرف را هم ساده می‌کند.

# اسکریپت با وابستگی در خود فایل (PEP 723)
# script.py:
# /// script
# requires-python = ">=3.11"
# dependencies = ["httpx", "rich"]
# ///

import httpx
from rich import print

print(httpx.get("https://httpbin.org/json").json())

# اجرا — uv خودکار محیط موقت می‌سازد و وابستگی را نصب می‌کند
uv run script.py

# اجرای ابزار بدون نصب دائم (مثل pipx / npx)
uvx ruff check .
uvx pytest

# نصب ابزار به‌صورت سراسری و ایزوله
uv tool install ruff
uv tool install poe-the-poet
uv tool list
uv tool update --all

PEP 723: وابستگی را داخل کامنت بالای اسکریپت بنویسید و با uv run script.py بدون venv اجرا کنید— عالی برای اسکریپت‌های دیتا و کرالر.
uvx: نام جدید uv tool run؛ هر ابزار را یک‌بار اجرا می‌کند بدون آلوده کردن محیط اصلی.
uv tool: برای ابزارهای همیشه‌حاضر مثل ruff، pytest، httpie؛ هر ابزار در venv ایزوله خودش نصب می‌شود.
uv run --with: وابستگی موقت تزریقی: uv run --with pandas script.py

این مدل «اسکریپت خودکفا» برای اشتراک‌گذاری نوت‌بوک یا اسکریپت پیش‌پردازش دیتاست فارسی بین هم‌تیمی‌ها، دردسر «اول venv بساز» را حذف می‌کند.

مقایسه uv با pip، Poetry و pip-tools

انتخاب ابزار به اندازه پروژه و نیاز به قفل تکرارپذیر بستگی دارد.

معیار	uv	pip + venv	Poetry	pip-tools
سرعت نصب (cache warm)	بسیار بالا (Rust + نصب موازی)	کند	کند تا متوسط	کند
قفل تکرارپذیر	بله، `uv.lock`	خیر (دستی `pip freeze`)	بله، `poetry.lock`	بله، `requirements.txt` کامپایل‌شده
مدیریت پایتون	بله، `uv python install`	خیر	خیر	خیر
اجرای اسکریپت بدون venv	بله، `uv run` + PEP 723	خیر	خیر	خیر
نصب ابزار ایزوله	بله، `uv tool / uvx`	خیر (نیاز به pipx)	خیر	خیر
سازگاری با pyproject.toml	کامل (PEP 621)	جزئی	کامل اما فرمت خاص	جزئی
مهاجرت	آسان از pip/Poetry	—	نیاز به تبدیل lock	آسان
مناسب برای	همه؛ از اسکریپت تا پروژه بزرگ AI	اسکریپت ساده یک‌بارمصرف	پروژه با Poetry مستقر	پروژه pip سنتی

اگر پروژه Poetry مستقر و تیم عادت کرده دارد، همان را نگه دارید. اگر CI کند، نصب تکراری دارید یا می‌خواهید pip و pyenv و pipx را با یک ابزار جایگزین کنید، مهاجرت به uv کم‌هزینه و پرمنفعت است. دستور uv sync جایگزین pip install -r requirements.txt و uv pip compile جایگزین pip-compile می‌شود.

کاربرد واقعی؛ راه‌اندازی پروژه AI با FastAPI و httpx

سناریوی کامل: یک سرویس کوچک AI که با FastAPI سرو می‌شود، با httpx به مدل خارجی می‌زند و با uv از init تا اجرا در یک دقیقه آماده می‌شود.

uv init ai-service --python 3.12
cd ai-service

# افزودن وابستگی‌های اصلی و dev
uv add fastapi uvicorn httpx pydantic
uv add --dev pytest httpx ruff

# ساخت یک API ساده: main.py
cat > main.py << 'PY'
from fastapi import FastAPI
import httpx

app = FastAPI()

@app.get("/health")
def health():
    return {"status": "ok"}

@app.get("/proxy")
def proxy():
    # نمونه: درخواست به سرویس بیرونی
    r = httpx.get("https://httpbin.org/json", timeout=10)
    return r.json()
PY

# اجرا
uv run fastapi dev main.py

# تست
uv run pytest -q

# لینت
uvx ruff check .

چرا uv run؟ هم پایتون درست را انتخاب می‌کند، هم .venv را می‌سازد و هم وابستگی قفل‌شده را نصب می‌کند؛ یک دستور به‌جای سه دستور.
CI: در GitHub Actions کافی است uv sync --frozen بزنید؛ نصب بدون resolver دوباره و سریع.
Docker: کافی است uv را در ایمیج کپی و uv sync --frozen --no-dev بزنید؛ لایه کش بهتر از pip است.
تکمیل زنجیره: همین سرویس را می‌توانید با آموزش بعدی تکمیل کنید؛ اگر API را نمی‌شناسید، آموزش FastAPI در پایتون و برای تست خودکارش آموزش Pytest در پایتون را ببینید.

# نمونه Dockerfile سبک با uv
FROM python:3.12-slim
COPY --from=ghcr.io/astral-sh/uv:latest /uv /bin/uv
WORKDIR /app
COPY pyproject.toml uv.lock ./
RUN uv sync --frozen --no-dev
COPY . .
CMD ["uv", "run", "fastapi", "run", "main.py", "--host", "0.0.0.0"]

اشتباهات رایج هنگام کار با uv

استفاده هم‌زمان از pip و uv بدون sync: با pip install دستی بسته‌ای اضافه می‌کنید ولی pyproject.toml و uv.lock بی‌خبر می‌ماند؛ همیشه uv add بزنید یا پس از pip دستی uv sync کنید.
فراموشی uv lock قبل از commit: وابستگی جدید را add کرده‌اید ولی lock را commit نکرده‌اید؛ هم‌تیمی با uv sync --frozen خطای ناسازگاری می‌گیرد.
sync بدون --dev و گلایه از نبود pytest: وابستگی‌های dev جدا هستند؛ برای CI تست باید uv sync --dev بزنید.
active کردن دستی venv: وقتی uv run دارید نیازی به source .venv/bin/activate نیست؛ فعال‌سازی دستی فقط در اشکال‌زدایی لازم است.
قفل با مirror ناقص: اگر از index خصوصی مثل Nexus استفاده می‌کنید، [[tool.uv.index]] در pyproject.toml را درست تعریف کنید وگرنه resolver از PyPI عمومی خطا می‌دهد.

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

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

برای پروژه جدید بله؛ uv تمام کارهای pip، virtualenv، pip-tools و بخش زیادی از Poetry را پوشش می‌دهد و با pyproject.toml استاندارد کار می‌کند. پروژه‌های Poetry مستقر را می‌توان با uv pip install یا با تبدیل pyproject.toml و تولید uv.lock مهاجرت داد، ولی اگر تیم و CI روی Poetry قفل است، الزامی به مهاجرت فوری نیست.

تفاوت uv pip و uv add چیست؟

uv pip install سازگار با pip است و فقط نصب می‌کند و روی pyproject.toml اثری ندارد— مناسب اسکریپت موقت یا نصب از requirements.txt. uv add وابستگی را به pyproject.toml اضافه و uv.lock را به‌روز می‌کند؛ برای پروژه رسمی همیشه add استفاده کنید.

چطور نسخه پایتون را با uv مدیریت کنم؟

با uv python install 3.11 3.12 نسخه‌ها را نصب، با uv python list ببینید و با uv venv --python 3.12 یا uv init --python 3.12 نسخه دلخواه را پین کنید. فایل .python-version مثل pyenv عمل می‌کند و uv run خودکار همان نسخه را می‌برد.

آیا uv برای نصب torch و بسته‌های سنگین مناسب است؟

بله و حتی بهتر؛ چون نصب موازی و کش هوشمند دارد. ناسازگاری CUDA را باید با index درست حل کنید؛ مثلاً برای PyTorch از uv add torch --index https://download.pytorch.org/whl/cu121 یا تعریف index در pyproject.toml استفاده کنید.

چطور ابزارهایی مثل ruff یا pytest را ایزوله نصب کنم؟

به‌جای pip install ruff سراسری، بزنید uv tool install ruff و سپس ruff check . از هر پوشه در دسترس است. برای اجرای یک‌باره بدون نصب، uvx ruff check . یا uvx pytest -q سریع‌ترین راه است و محیط پروژه را آلوده نمی‌کند.

آیا uv با Docker و CI سازگار است؟

کاملاً؛ در CI از uv sync --frozen برای نصب دقیق از lock استفاده کنید و کش ~/.cache/uv را cache کنید. در Docker ایمیج Astral (ghcr.io/astral-sh/uv) را کپی و uv sync --frozen --no-dev بزنید تا لایه وابستگی کش شود و بیلد ثانیه‌ای شود.

جمع‌بندی

uv را از astral.sh/uv/install.sh یا pipx install uv نصب و با uv --version صحت را چک کنید.
برای اسکریپت: uv venv && uv pip install یا مستقیم uv run --with؛ برای پروژه: uv init سپس uv add و uv sync.
هر وابستگی جدید را با uv add اضافه و uv.lock را commit کنید؛ نصب تمیز با uv sync --frozen.
اسکریپت خودکفا را با هدر PEP 723 و uv run script.py بسازید؛ ابزارها را با uvx یا uv tool install ایزوله اجرا کنید.
از امروز یک پروژه کوچک مثل ai-service بالا را بسازید، به Git ببرید و CI را روی uv sync بگذارید تا سرعت را لمس کنید.

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