uv

تفتح مشروع Python قديمًا فتجد أن الحزم المثبتة على جهازك لا تطابق جهاز زميلك، أو تتنقل بين أوامر إنشاء البيئة وتثبيت الاعتماديات وتشغيل أدوات الفحص. يساعدك uv على جمع هذه الخطوات في سير عمل واحد: تصف ما يحتاجه المشروع، وتحفظ النسخ المحلولة في ملف قفل، ثم تشغّل الكود داخل بيئته. الفائدة ليست أمرًا أقصر فقط، بل جعل إعداد المشروع ومراجعته وتسليمه أوضح لفرد أو فريق صغير.

🧭 ما uv وكيف يعمل؟

uv أداة مفتوحة المصدر من Astral لإدارة حزم Python ومشاريعها وبيئاتها، مكتوبة بلغة Rust. تعمل من الطرفية، ويمكنها إدارة إصدارات Python وتشغيل أدوات سطر الأوامر والسكربتات أيضًا. ليست محرر كود، ولا وكيل ذكاء اصطناعي، ولا خدمة سحابية تكتب البرنامج عنك.

في مشروع تديره uv، يصف pyproject.toml اعتماديات المشروع ومتطلبات Python. ويسجل uv.lock نسخ الاعتماديات التي اختارها محلل الحزم، مع معلومات الاختلاف بين الأنظمة وإصدارات Python. أما .venv فهي البيئة المحلية التي تُثبت فيها الحزم. تحتفظ بالملفين الأولين في Git، ولا ترفع مجلد البيئة. ينشئ uv lock ملف القفل أو يحدثه دون إنشاء البيئة؛ أما uv sync فيجهز البيئة وفق الاعتماديات المحددة.

رسم توضيحي أصلي للعلاقة بين ملفات المشروع والبيئة المحلية، وليس لقطة شاشة من uv. ملف القفل لا يحل محل تثبيت الحزم على كل جهاز.

🎯 كيف ستفيدك في العمل اليومي؟

تخيل أنك تكتب سكربت تقرير أسبوعي، ثم تريد أن يشغله زميلك أو خط الاختبار الآلي. بدل إرسال قائمة حزم مكتوبة يدويًا مع تعليمات تفعيل البيئة، تحفظ تعريف المشروع وملف القفل وتستخدم أمر تشغيل واضحًا. وعند إضافة مكتبة، يظهر التغيير في Git ويمكن مراجعته مع الكود.

القيمة المضافة هي تقليل القرارات المتفرقة: أي Python؟ أي نسخ للحزم؟ هل هذه أداة عامة أم اعتماد للمشروع؟ uv يوفر مسارات مختلفة لهذه الحالات بدل خلطها في بيئة واحدة. لكنه لا يضمن أن الكود صحيح، ولا أن مكتبة أصلية ستتوفر لكل نظام. كما أن قابلية تكرار اعتماديات Python لا تعني تطابق نظام التشغيل أو مكتباته الخارجية تلقائيًا.

🌟 الميزات والقدرات الرئيسية

1. ملف قفل وتشغيل مرتبط بحالة المشروع

يحل uv.lock مشكلة الاعتماد على ما هو مثبت عَرَضًا على جهاز المطور. يحفظ نتيجة حل الاعتماديات، بينما تبقى الحدود المسموح بها في pyproject.toml. عند التشغيل العادي، يفحص uv حالة المشروع ويحدث القفل إن احتاج، ثم يزامن الاعتماديات المطلوبة قبل تنفيذ الأمر.

• أين تجدها: أوامر uv lock وuv sync وuv run داخل مجلد المشروع.
• كيف تستخدمها: أضف مكتبة باستخدام uv add rich، ثم شغّل سكربتك بـ uv run report.py. راجع التغييرات في ملفي المشروع والقفل معًا.
• مثال عملي توضيحي: في الاختبار الآلي، استخدم uv run --locked report.py لرفض التشغيل إذا احتاج القفل إلى تحديث، بدل تعديل ملف ملتزم به أثناء الفحص.
• انتبه: --frozen يستخدم ملف القفل الموجود دون التحقق من توافقه الحالي مع تعريف المشروع. لا يعني «أكثر أمانًا» أو «دون شبكة». كذلك لا يجعل صدور نسخة جديدة من مكتبة ملف القفل قديمًا تلقائيًا؛ الترقية قرار منفصل.

رسم أصلي يشرح الفرق بين تحديث القفل، ورفض القفل غير المتوافق، وتجاوز فحص توافقه. أوضاع القفل لا تمنع تنفيذ الكود أو الوصول إلى الشبكة.

هناك فرق آخر مهم: uv sync يطبق مزامنة دقيقة افتراضيًا، فيزيل من بيئة المشروع الحزم غير المطلوبة وفق الاختيار الحالي. أما uv run فمزامنته غير دقيقة افتراضيًا، فلا يزيل الحزم الإضافية بالطريقة نفسها. لذلك لا تثبت حزمًا يدويًا داخل .venv ثم تعتمد على بقائها بعد uv sync؛ سجّل الاعتماديات اللازمة في إعداد المشروع.

2. أدوات الطرفية خارج اعتماديات التطبيق

قد تحتاج إلى فاحص مثل Ruff دون إضافته إلى كل مشروع أو تثبيته في Python العام. يوفر uvx، وهو اختصار لـ uv tool run، بيئة أداة معزولة داخل ذاكرة uv المؤقتة. وتُخزّن هذه البيئة لإعادة استخدامها؛ ليست بيئة تُحذف بالضرورة بعد كل تشغيل.

• أين تجدها: uvx للتشغيل عند الحاجة، وuv tool install لتثبيت أداة تستخدمها باستمرار.
• كيف تستخدمها: uvx ruff check يفحص المسار الحالي. أما uv tool install ruff فينشئ بيئة دائمة خاصة بالأداة ويوفر أمرها ضمن مسار أوامر المستخدم وفق إعداد التثبيت.
• مثال عملي توضيحي: افحص مشروعًا سريعًا دون إضافة Ruff إلى اعتماديات التطبيق. إذا كانت نسخة الفاحص جزءًا من عقد الفريق، ثبّتها في إعداد المشروع أو حدد نسخة الأداة صراحة ضمن سياسة الفريق بدل الاعتماد على اختيار متغير.
• انتبه: عندما تحتاج الأداة إلى استيراد اعتماديات المشروع، كما يحدث عادة مع اختبارات pytest، استخدم مسار المشروع وuv run بدل افتراض أن uvx يرى البيئة نفسها. وتشغيل أداة معزولة لا يمنعها من قراءة ملفاتك أو تعديلها.

رسم أصلي يقارن التشغيل عند الطلب بالتثبيت الدائم. كلاهما يفصل اعتماديات الأداة عن المشروع، لكنه لا يوفر صندوق عزل أمنيًا.

قد يعيد uvx استخدام نسخة سبق حلها وتخزينها، وقد يستخدم بيئة أداة مثبتة مطابقة. لا تتوقع الترقية في كل مرة. حدّد النسخة عند الحاجة إلى الثبات، وراجع الترقيات المقصودة بدل تحويل كل تشغيل إلى تحديث غير ملحوظ.

3. سكربت يحمل تعريف اعتمادياته داخله

ليست كل مهمة بحاجة إلى مشروع كامل. يدعم uv بيانات السكربت المضمنة وفق PEP 723: تكتب متطلبات Python والحزم في كتلة تعليقات داخل ملف .py، فيجهز بيئة مناسبة لتشغيله. هذا مفيد لسكربت شخصي صغير تريد مشاركته دون مطالبة القارئ بتخمين المكتبات المطلوبة.

• أين تجدها: دليل السكربتات، والأمر uv add --script report.py rich، ثم uv run report.py.
• كيف تستخدمها: أضف البيانات المضمنة إلى السكربت بدل الاعتماد على بيئة Python العامة. يتولى uv قراءة هذه البيانات عند التشغيل.
• مثال عملي توضيحي: سكربت تقرير يستخدم Rich يحمل سطر الاعتماد داخل كتلة # /// script، فيعرف uv ما الذي يلزمه قبل التنفيذ.
• انتبه: السكربت ذو البيانات المضمنة يعمل في بيئة معزولة، وتُتجاهل اعتماديات المشروع المحيط به. لا تضف هذه البيانات إلى سكربت يحتاج بيئة المشروع ثم تتوقع استمرار وراثتها.

رسم أصلي لمسار السكربت ذي البيانات المضمنة. يظهر اسم الحزمة للتوضيح فقط؛ لا يعرض نتيجة تشغيل فعلية.

للتوضيح، قد يحتوي الملف على:

# /// script
# requires-python = ">=3.12"
# dependencies = ["rich"]
# ///
from rich import print
print("[green]Weekly report ready[/green]")

حقل dependencies مطلوب في هذه البيانات ولو كانت قائمته فارغة. وإذا احتجت قفلًا للسكربت، فإن uv lock --script report.py ينشئ report.py.lock صراحة؛ لا تفترض وجود قفل تلقائي لكل سكربت. المثال هنا تعليمي ولم ننفذه.

🪜 مثال متكامل: مشروع تقرير صغير

هذا المسار مختلف عن مثال السكربت المستقل أعلاه: هنا ستستخدم اعتماديات المشروع، لذا لا تضف كتلة البيانات المضمنة إلى report.py.

1. بعد تثبيت uv، أنشئ مشروعًا وادخل إليه:

uv init report-demo
cd report-demo
uv add rich

1. أنشئ بنفسك ملفًا باسم report.py في جذر المشروع، واكتب فيه:

from rich import print

items = ["Collect data", "Review totals", "Send summary"]
for number, item in enumerate(items, start=1):
    print(f"[cyan]{number}.[/cyan] {item}")

1. شغّله من المجلد نفسه:

uv run report.py

النتيجة المتوقعة قائمة بثلاث مهام مرقمة مع تنسيق لوني في طرفية تدعم ذلك. هذا مثال موثق منطقيًا، لا اختبار نفذناه أو قياسًا للأداء. ينتج uv init في الإصدار المفحوص هيكل حزمة افتراضيًا؛ ملف report.py هنا ملف تضيفه أنت، وليس ملفًا ندّعي أن الأمر أنشأه.

1. راجع وأضف إلى Git تعريف المشروع وملف القفل وملفات المصدر ذات الصلة. لا تضف .venv. من نسخة مستنسخة، يمكن لزميلك استخدام uv sync --locked ثم uv run --locked report.py؛ يلزمه Python مناسب واتصال للحصول على الموارد غير المتوفرة محليًا.

2. عند الحاجة إلى ترقية مقصودة، استخدم uv lock --upgrade-package rich، وراجع فرق القفل واختبر الكود. تحديث القفل وحده لا يزامن البيئة؛ التشغيل أو المزامنة خطوة لاحقة. لا يوجد ضمان بأن الترقية متوافقة مع منطق برنامجك.

⚖️ ماذا تضيف مقارنة بالعمل اليدوي؟

هذه فروق في تنظيم العمل، وليست نسب توفير وقت مقاسة. يمكن لـ pip وvenv وسير عمل منضبط أداء كثير من هذه المهام؛ ميزة uv العملية هي جمع المسارات وتوضيح حالتها.

⚙️ الإعدادات التي تحتاجها فعلًا

ابدأ بإعدادات قليلة. استخدم requires-python في pyproject.toml لتحديد نطاق Python الذي يدعمه المشروع. ويمكن حفظ اختيار محلي للإصدار عبر uv python pin 3.12 في .python-version، مع مراعاة سياسة فريقك. هذا لا يعوض اختبار التطبيق على الإصدارات التي تزعم دعمها.

تعيش إعدادات uv في [tool.uv] داخل pyproject.toml أو في uv.toml. عند استخدام مستودع حزم خاص، اضبط عنوان الفهرس وآلية الاعتماد وفق وثائق الشركة؛ لا تلصق كلمة المرور داخل ملف سيُرفع إلى Git. ذاكرة الحزم المؤقتة وبيئة المشروع وبيئات الأدوات ليست المجلد نفسه، ولا تحتاج إلى نقلها إلى زميلك كي تشاركه تعريف المشروع.

🚀 التثبيت والبدء

الإصدار المستقر المرصود هو 0.13.3، منشور في 20 أكتوبر 2026. الثنائيات الرسمية جاهزة؛ لا تحتاج إلى تثبيت Rust لبنائها إن استخدمت ملفًا جاهزًا، ويمكن للتثبيت المستقل العمل دون وجود Python مسبقًا. وقد ينزّل uv إصدار Python مطلوبًا إن لم يجده، لذلك راجع سياسة الشبكة والتنزيل في بيئتك.

على جهاز يملك Homebrew مسبقًا، توثق Astral الأمر:

brew install uv
uv --version

وعلى Windows مع WinGet:

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

تتوفر أيضًا ملفات إصدار ومثبت مستقل رسمي. تعرض الوثائق مثبت shell عبر الإنترنت؛ تنزيل نص وتشغيله يمنحه صلاحيات مستخدمك، فراجع مصدره ومحتواه وسياسة مؤسستك قبل التنفيذ. لا يلزم استخدام sudo لمجرد تشغيل المثال، ولا نطلب منك رفع صلاحيات النظام.

أوامر مديري الحزم قد تثبت نسخة أحدث أو تتأخر عن الإصدار المرصود؛ تحقق من ناتج uv --version. أما uv version فله وظيفة مختلفة مرتبطة بنسخة المشروع، وليس أمر التحقق المقصود هنا. بعد التثبيت، ابدأ بمشروع تجريبي لا بمستودع إنتاجي غير محفوظ.

🔗 التوافق والتكاملات

تدعم السياسة الرسمية macOS وLinux وWindows بمستويات اختبار مختلفة؛ من منصات المستوى الأول macOS على Intel وApple Silicon، وLinux وWindows على x86_64. لا يعني ذلك تماثل دعم جميع المعماريات. راجع جدول المنصات، خصوصًا على ARM أو الأنظمة القديمة؛ تذكر الوثائق macOS 13 فأحدث وWindows 10/Server 2016 كحدود أساسية، مع تفاصيل واستثناءات للمنصات في المرجع.

يسجل مرجع Python للإصدار المفحوص دعم CPython بمستوى أول، ويعدد Python 3.10–3.15 ضمن ذلك المستوى؛ وجود دعم للأقدم لا يجعله خيارًا أمنيًا مناسبًا. توافق حزمة معينة يعتمد على الحزمة نفسها ونسخة Python والمنصة، لا على uv وحده.

يمكن استخدام أوامر uv من طرفية أي محرر أو في CI؛ ليست هذه إضافة خاصة لـ Cursor أو Claude Code، ولا نثبت توافقًا رسميًا مع وكيل بعينه. التكامل المباشر هنا مع Git عبر ملفات نصية قابلة للمراجعة، ومع فهارس حزم Python. دعم uv لا يعني أن كل أمر pip أو كل إعداد لمشروع قديم يمكن نقله دون مراجعة.

💰 التكلفة والتشغيل المحلي

الأداة الأساسية مجانية ومفتوحة المصدر بترخيص MIT أو Apache-2.0 وفق اختيارك كما يوضح المستودع، ولا تحتاج اشتراكًا أو API مدفوعًا لتشغيلها. ترخيص uv لا يحدد تراخيص المكتبات التي ستثبتها، وقد تكون بعض الفهارس أو الخدمات المرتبطة بمشروعك مدفوعة على حدة.

إدارة المشروع تتم محليًا. لكن التثبيت وحل الحزم وتنزيل Python والأدوات قد تتصل بخوادم الفهارس والتنزيل. لا يعد المثال إرسالًا للكود إلى نموذج AI، ولا نعد بعدم وجود أي حركة شبكة أو بأننا أجرينا تدقيقًا شبكيًا شاملًا. تتوقف إمكانية العمل دون اتصال على ما هو مخزن محليًا وعلى أوامرك وإعداداتك؛ --frozen ليس وضعًا دون اتصال.

⚠️ الحدود ومتى لا تستخدمها

لا تستخدم uv بديلًا عن Docker لعزل نظام التشغيل، أو عن مدير مكتبات النظام عند الحاجة إلى مكتبات أصلية، أو عن اختبارات التطبيق. وقد تتطلب الحزم التي تُبنى من المصدر مترجمًا وأدوات إضافية. لا تضمن ملفات القفل نجاح كل بناء على جهاز مختلف.

إذا كان الفريق يعتمد بالفعل Poetry أو pip-tools أو سيرًا مستقرًا، فابدأ بمشروع صغير وقارن تكلفة الانتقال بدل إنشاء ملفي قفل متنافسين بلا سياسة. وإذا كانت مهمتك تجميع ملفات مستودع لسياق مساعد AI، فهذه مشكلة مختلفة تعالجها أدوات مثل Repomix، وليست سببًا لاختيار uv.

قورنت uv هنا مع Repomix من مجال تجهيز سياق الكود؛ كلاهما مستقل عن DSH. رجحت uv لأنها تعالج حالة تشغيل واعتماديات متكررة يمكن شرحها والتحقق منها مباشرة، لا لأنها تتفوق بعدد النجوم. ولم ننفذ تثبيتًا أو ترحيلًا أو اختبار سرعة فعليًا.

🔐 الأمان والصلاحيات

uv يكتب ملفات المشروع وبيئته وذاكرته المؤقتة، وقد ينزل Python وحزمًا ويشغل أوامر. مكتبة غير موثوقة أو أداة تشغلها يمكن أن تنفذ كودًا بصلاحيات حسابك. البيئة الافتراضية تفصل الاعتماديات، لكنها ليست حاجزًا يمنع الوصول إلى الملفات أو الشبكة أو الأسرار.

راجع مصدر الحزم وأسماءها، وافحص فروق القفل في طلبات الدمج، واستخدم صلاحيات محدودة في CI. لا تشغّل سكربتًا من مستودع مجهول لمجرد أن uv يستطيع تثبيت اعتمادياته. وإذا كانت لديك بيانات خاصة أو مفاتيح لفهرس داخلي، فضعها في آلية اعتماد مناسبة ولا تكتبها في ملفات الشرح أو Git. القفل يضبط نسخ الاعتماديات، وليس شهادة خلوها من الثغرات.

📚 المصادر وتاريخ التحقق

تم التحقق في 20 أكتوبر 2026 من المستودع الأصلي ووثائق الإصدار 0.13.3. رُصدت 90,917 نجمة و3,674 تفرعًا لمستودع astral-sh/uv؛ وآخر دفع مسجل كان 20 أكتوبر 2026، 03:00:50 UTC. هذه لقطة زمنية لا تقييم جودة ولا ضمان تحديث الصفحة اللحظي.

• المستودع الأصلي وبيان الترخيص.
• الإصدار 0.13.3 وتاريخه.
• دليل التثبيت الرسمي.
• دليل المشاريع وسلوك القفل والمزامنة.
• تشغيل الأدوات وبيئات الأدوات.
• تشغيل السكربتات والبيانات المضمنة.
• سياسة المنصات وسياسة Python.
• وثائق مثبتة على الإصدار المفحوص للمراجعة إذا تغيرت الوثائق الحية.
• الاكتشاف والمقارنة: GitHub Topics: package-manager، فهرس مهارات Claude، DSH Market، ومستودع Repomix. رُصدت لـ Repomix 28,915 نجمة و1,707 تفرعات، وإصدار v1.18.1 بتاريخ 21 سبتمبر 2026، وترخيص MIT ومتطلب Node.js 22 فأحدث.

نطاق التحقق: قراءة المصادر والملفات الرسمية، ومراجعة الأمثلة والرسوم. لم نثبت uv أو Ruff أو حزم المثال، ولم ننفذ الأوامر أو نقس الأداء أو نجر تدقيقًا أمنيًا مستقلًا. الرسوم تفسيرية أصلية وليست نتائج تشغيل أو واجهة منتج مصطنعة.