نقطة
الكتابات/tutorial/2026/06
● Tutorial6 يونيو 2026·24 دقيقة

uv: الدليل الكامل لمدير حزم بايثون فائق السرعة (2026)

أتقن أداة uv — مدير حزم ومشاريع بايثون المكتوب بلغة Rust والذي يحل محل pip و pip-tools و pipx و poetry و pyenv بأداء أسرع بـ 10 إلى 100 مرة. يغطي هذا الدليل التثبيت وإعداد المشاريع ومجموعات الاعتماديات وملفات القفل والأدوات وإدارة إصدارات بايثون ومساحات العمل و Docker.

AI Bot
AI Bot
Author
·EN · FR · AR

المتطلبات المسبقة

قبل البدء بهذا الدليل، تأكد من توفر ما يلي:

  • طرفية (macOS أو Linux أو Windows مع PowerShell)
  • إلمام أساسي بسطر الأوامر
  • خبرة سابقة بسيطة مع بايثون و pip (مفيدة وليست إلزامية)
  • لا حاجة لوجود تثبيت بايثون مسبق — تستطيع uv إدارة بايثون نيابة عنك

ماذا ستتعلم

بنهاية هذا الدليل ستكون قادراً على:

  • تثبيت uv وفهم سبب استبداله لمجموعة كاملة من الأدوات
  • إنشاء وهيكلة مشروع بايثون باستخدام ملف pyproject.toml
  • إضافة وإزالة وتثبيت الاعتماديات مع ملف قفل قابل لإعادة الإنتاج
  • إدارة إصدارات بايثون دون الحاجة إلى pyenv
  • تشغيل أدوات سطر الأوامر دون تلويث بيئتك العامة
  • تنظيم المستودعات أحادية البنية (monorepo) باستخدام مساحات العمل
  • بناء صورة Docker سريعة ومُخزّنة مؤقتاً للإنتاج

لماذا uv؟

طوال أكثر من عقد، تعامل مطورو بايثون مع صندوق أدوات مربك: pip للتثبيت، و pip-tools أو poetry للقفل، و virtualenv للعزل، و pyenv لتبديل إصدارات بايثون، و pipx لتشغيل الأدوات العامة. كل أداة لها إعداداتها الخاصة، ونزواتها الخاصة، وسقف أدائها الخاص.

أداة uv، المكتوبة بلغة Rust بواسطة فريق Astral (نفس فريق أداة الفحص Ruff)، تدمج هذه المجموعة بأكملها في ملف تنفيذي واحد. وهي غالباً أسرع بـ 10 إلى 100 مرة من سير العمل المعتمد على pip، لأنها توازي عمليات التنزيل، وتخزّن مؤقتاً بقوة عبر مخزن عالمي معنوَن بالمحتوى، وتحلّ الاعتماديات بمحلّل مصمم لهذا الغرض.

أبرز الفوائد:

  • أداة واحدة، إعداد واحد. تعيش المشاريع في ملف pyproject.toml قياسي، مقفولة عبر ملف uv.lock.
  • السرعة. تبدو عمليات التثبيت الباردة فورية؛ والتثبيت الدافئ شبه فوري بفضل إعادة استخدام ذاكرة التخزين المؤقت بروابط صلبة.
  • إدارة بايثون مدمجة. تنزّل uv وتثبّت مفسّرات بايثون بنفسها — لا حاجة لبايثون النظام.
  • توافق فوري مع pip. تتيح واجهة uv pip الانتقال التدريجي.

الخطوة 1: تثبيت uv

تأتي uv كملف تنفيذي مستقل دون أي متطلب مسبق من بايثون.

على macOS أو Linux:

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

على Windows (عبر PowerShell):

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

يمكنك أيضاً تثبيتها عبر Homebrew أو pipx أو حتى pip:

brew install uv
# أو
pipx install uv

تحقق من التثبيت واعرف كيفية تحديثها:

uv --version
uv self update

نصيحة: تثبّت uv افتراضياً في ~/.local/bin. إذا لم يتم العثور على uv --version، أضف هذا المسار إلى PATH وأعد تشغيل الطرفية.

الخطوة 2: إنشاء مشروعك الأول

لنُنشئ هيكل مشروع. تدعم uv عدة تخطيطات — --app للتطبيقات، و --lib للمكتبات القابلة للتوزيع، و --package للتطبيقات المُحزّمة مع خلفية بناء.

uv init weather-cli --app
cd weather-cli

ينتج عن ذلك نقطة انطلاق نظيفة:

weather-cli/
├── .python-version
├── README.md
├── main.py
└── pyproject.toml

ملف pyproject.toml هو المصدر الوحيد للحقيقة:

[project]
name = "weather-cli"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.12"
dependencies = []

لاحظ أنه لا توجد بيئة افتراضية بعد ولا خطوة لتثبيت بايثون. تنشئ uv كليهما بشكل كسول في أول مرة تضيف فيها اعتمادية أو تشغّل كوداً.

الخطوة 3: إضافة وإزالة الاعتماديات

إضافة حزمة تنجز ثلاثة أمور دفعة واحدة: تحدّث pyproject.toml، وتنشئ .venv إن لزم، وتكتب ملف القفل.

uv add httpx rich

سترى uv تحلّل وتنزّل وتثبّت في جزء من الثانية:

Using CPython 3.12.4
Creating virtual environment at: .venv
Resolved 8 packages in 12ms
Installed 8 packages in 23ms
 + httpx==0.27.2
 + rich==13.9.4
 ...

تحتاج نطاق إصدار محدد؟ مرّر القيد مباشرة:

uv add "httpx>=0.27,<1.0"

الإزالة متماثلة وتحدّث ملف القفل أيضاً:

uv remove rich

للحزم ذات الميزات الاختيارية (extras)، استخدم --extra:

uv add fastapi --extra standard

الخطوة 4: مجموعات الاعتماديات لأدوات التطوير

يجب ألا تختلط اعتماديات الإنتاج باعتماديات التطوير. تستخدم uv جدول [dependency-groups] القياسي، مع مجموعة dev مدمجة.

أضف الأدوات التي تهم أثناء التطوير فقط:

uv add --dev pytest ruff mypy

يسجّلها ملف pyproject.toml بشكل منفصل الآن:

[dependency-groups]
dev = [
    "pytest>=8.3.0",
    "ruff>=0.8.0",
    "mypy>=1.13.0",
]

يمكنك تعريف مجموعات مسماة عشوائية أيضاً — مثلاً مجموعة docs:

uv add --group docs mkdocs mkdocs-material

عند النشر، ثبّت ما يحتاجه الإنتاج فقط:

uv sync --no-dev

لماذا هذا مهم: إبقاء أدوات الفحص ومدققي الأنواع ومشغّلات الاختبار خارج صورة الإنتاج يجعل البناء أصغر وأسرع وأكثر أماناً.

الخطوة 5: ملفات القفل وإمكانية إعادة الإنتاج

في كل مرة تتغير الاعتماديات، تحدّث uv ملف uv.lock — وهو لقطة محلولة بالكامل، عابرة للأنظمة، ومُجزّأة (hashed) لشجرة اعتمادياتك بأكملها. أودِعه في نظام التحكم بالإصدارات.

لإعادة توليد ملف القفل صراحةً:

uv lock

لمزامنة بيئتك مع ملف القفل (الأمر الذي ستشغّله أكثر شيء في CI):

uv sync

لترقية حزمة واحدة ضمن قيودها:

uv lock --upgrade-package httpx

لترقية كل شيء:

uv lock --upgrade

في CI تريد أن يفشل البناء بصوت عالٍ إذا كان ملف القفل قديماً بدلاً من إعادة توليده بصمت:

uv sync --locked

هذا الخيار يؤكد أن ملف القفل محدّث بالفعل — مثالي لخطوط الأنابيب القابلة لإعادة الإنتاج.

الخطوة 6: تشغيل الكود والسكربتات

لن تحتاج لتفعيل بيئة افتراضية مجدداً. ينفّذ uv run أمراً داخل بيئة المشروع، مع مزامنة الاعتماديات أولاً عند الحاجة.

uv run main.py
uv run pytest
uv run ruff check

ولأن uv تضمن تطابق البيئة مع ملف القفل قبل التشغيل، تختفي إلى حد كبير أخطاء "تعمل على جهازي".

تدعم uv أيضاً اعتماديات السكربت المضمّنة — يستطيع سكربت بملف واحد إعلان اعتمادياته الخاصة باستخدام معيار PEP 723:

# /// script
# requires-python = ">=3.12"
# dependencies = ["httpx", "rich"]
# ///
 
import httpx
from rich import print
 
resp = httpx.get("https://api.github.com")
print(resp.json())

شغّله بدون أي إعداد — تنشئ uv بيئة مؤقتة فوراً:

uv run fetch_repos.py

يمكنك حتى إضافة اعتمادية إلى كتلة بيانات السكربت المستقل تلقائياً:

uv add --script fetch_repos.py pandas

الخطوة 7: إدارة إصدارات بايثون

تستبدل uv أداة pyenv بالكامل. تستطيع تنزيل وتبديل إصدارات CPython دون لمس بايثون النظام لديك.

اعرض المتاح وثبّت إصدارات محددة:

uv python list
uv python install 3.11 3.12 3.13

ثبّت المشروع على مفسّر معين — هذا يكتب ملف .python-version:

uv python pin 3.12

عند تشغيل uv sync أو uv run، تستخدم uv تلقائياً المفسّر المثبّت (وتنزّله إن لزم). يستنسخ المساهمون الجدد المستودع ويحصلون على إصدار بايثون الدقيق دون أي إعداد يدوي.

الخطوة 8: تشغيل الأدوات عبر uvx

للأدوات السطرية لمرة واحدة التي لا تريدها في مشروعك — المنسّقات، أدوات السقالات، عملاء HTTP — توفر uv مشغّلاً معزولاً. و uvx اختصار لـ uv tool run.

شغّل أداة في بيئة مؤقتة:

uvx ruff check .
uvx cowsay -t "uv is fast"

إن أردت أداة متاحة بشكل دائم على PATH (حالة استخدام pipx)، ثبّتها:

uv tool install ruff
uv tool list
uv tool upgrade --all

تحصل كل أداة على بيئتها المعزولة، فلا تتعارض اعتمادياتها مع بعضها ولا مع مشاريعك أبداً.

الخطوة 9: مساحات العمل للمستودعات أحادية البنية

غالباً ما تحتوي القواعد البرمجية الكبيرة على عدة حزم مترابطة. تتيح مساحات عمل uv، المستوحاة من Cargo، لعدة حزم مشاركة ملف قفل واحد وبيئة افتراضية واحدة مع بقائها قابلة للبناء باستقلالية.

عرّف مساحة العمل في ملف pyproject.toml الجذري:

[tool.uv.workspace]
members = ["packages/*"]

ثم اجعل حزمة تعتمد على أخرى باستخدام مصدر مساحة العمل:

[project]
dependencies = ["shared-core"]
 
[tool.uv.sources]
shared-core = { workspace = true }

الآن تحلّ uv sync مساحة العمل بأكملها معاً، ويصبح أي تغيير في shared-core مرئياً فوراً لكل حزمة تعتمد عليه — دون نشر ودون إعادة تثبيت.

أما للاعتماديات القادمة من Git أو مسار محلي، فيتولى [tool.uv.sources] ذلك أيضاً:

[tool.uv.sources]
my-lib = { git = "https://github.com/acme/my-lib", tag = "v1.2.0" }
local-tool = { path = "../local-tool", editable = true }

الخطوة 10: البناء والنشر

عندما تجهز مكتبتك للمشاركة، تبني uv توزيعات wheel و source قياسية:

uv build

تحط الناتجات في مجلد dist/. انشرها إلى PyPI (أو فهرس خاص) عبر:

uv publish

استخدم رمزاً (token) عبر متغير البيئة UV_PUBLISH_TOKEN بدلاً من كتابة بيانات الاعتماد ضمن الكود.

الخطوة 11: صورة Docker للإنتاج

تتألق uv في الحاويات بفضل تركيبات ذاكرة التخزين المؤقت والتثبيت المدفوع بملف القفل. النمط أدناه يثبّت الاعتماديات في طبقة مخزّنة مؤقتاً قبل نسخ كودك المصدري، حتى لا تُبطل تغييرات الكود ذاكرة اعتماديات التخزين المؤقت.

FROM python:3.12-slim
 
# نسخ الملف التنفيذي uv من الصورة الرسمية
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
 
WORKDIR /app
 
# تثبيت الاعتماديات أولاً باستخدام تركيب cache و bind mounts
RUN --mount=type=cache,target=/root/.cache/uv \
    --mount=type=bind,source=uv.lock,target=uv.lock \
    --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
    uv sync --locked --no-install-project --no-dev
 
# الآن نسخ المشروع وتثبيته
COPY . /app
RUN --mount=type=cache,target=/root/.cache/uv \
    uv sync --locked --no-dev
 
# التشغيل داخل البيئة المزامَنة
CMD ["uv", "run", "main.py"]

المزامنة على مرحلتين — الاعتماديات أولاً ثم المشروع — تعني أنه طالما بقي uv.lock و pyproject.toml دون تغيير، يعيد Docker استخدام طبقة الاعتماديات الثقيلة ويعيد بناء طبقة المشروع الصغيرة فقط.

الانتقال من pip أو Poetry

لست مضطراً لإعادة كتابة كل شيء دفعة واحدة. تأتي uv بواجهة متوافقة مع pip:

uv pip install -r requirements.txt
uv pip compile requirements.in -o requirements.txt
uv venv

للانتقال الكامل، شغّل uv init في مشروع قائم، وانقل مدخلات requirements.txt إلى pyproject.toml عبر uv add، وأودِع ملف uv.lock المُولّد. تستخدم مشاريع Poetry ملف pyproject.toml أصلاً، فالمهمة الرئيسية هي ترجمة قسم [tool.poetry.dependencies] إلى جدول [project] dependencies القياسي وتشغيل uv lock.

اختبار إعدادك

تحقق من سير العمل بالكامل من البداية للنهاية:

uv init demo --app && cd demo
uv add httpx
uv add --dev pytest
uv run python -c "import httpx; print(httpx.__version__)"
uv sync --locked
uv tree

إذا طبع uv tree رسم شجرة اعتمادياتك وخرج uv sync --locked بنظافة، فمشروعك قابل لإعادة الإنتاج وجاهز لـ CI.

استكشاف الأخطاء وإصلاحها

uv: command not found بعد التثبيت — مجلد الملف التنفيذي (~/.local/bin) ليس على PATH. أضفه وأعد تشغيل الطرفية.

ملف القفل يتغير باستمرار في CI — أنت تشغّل uv sync بدلاً من uv sync --locked. استخدم النسخة المقفولة في خطوط الأنابيب حتى يُفشل ملف القفل القديم البناءَ بدلاً من إعادة كتابته بصمت.

اختيار إصدار بايثون الخاطئ — تحقق من وجود ملف .python-version شارد أو قيد requires-python يستبعد مفسّرك. شغّل uv python pin لضبط الإصدار صراحةً.

أول تثبيت بطيء — التشغيل الأول فقط هو من يملأ ذاكرة التخزين المؤقت العالمية. عمليات التثبيت اللاحقة عبر كل المشاريع تعيد استخدام ملفات بروابط صلبة وتكون أسرع بشكل كبير.

الخطوات التالية

  • ادمج uv مع Ruff (من Astral أيضاً) لإعداد موحّد للفحص والتنسيق مدعوم بـ Rust
  • استكشف اعتماديات السكربت المضمّنة لأتمتة سريعة وسكربتات بيانات
  • أضف uv sync --locked إلى CI قبل الاختبارات لضمان تشغيلات قابلة لإعادة الإنتاج
  • اقرأ المزيد من أدلة أدوات بايثون على noqta.tn، بما في ذلك دليل FastAPI Docker للإنتاج و عملاء Pydantic AI الآمنون نوعياً

الخاتمة

تدمج uv مشهد أدوات بايثون المجزأ في أداة واحدة سريعة ومتماسكة. بملف تنفيذي واحد تُنشئ هياكل المشاريع، وتدير الاعتماديات وإصدارات بايثون، وتقفل لإعادة الإنتاج، وتشغّل أدوات معزولة، وتنظّم المستودعات أحادية البنية، وتشحن صور Docker رشيقة. السرعة هي الطُّعم، لكن المكسب الحقيقي هو نموذج ذهني واحد بدلاً من خمسة. ثبّتها، وشغّل uv init، ونادراً ما ستلجأ إلى pip أو poetry أو pyenv أو pipx مجدداً.