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

لماذا تتعطل البيئة المنقولة

تخزن البيئة الافتراضية تكوين بايثون الخاص بها وتنشئ نصوصًا برمجية مثبتة بمسارات تشير إلى مفسر البيئة. عند نقل مجلد المشروع، قد تظل هذه المسارات تشير إلى الموقع القديم. يمكن أن يؤدي ذلك إلى جعل source .venv/bin/activate يشير إلى ملف مفقود، أو يجعل أمرًا مثبتًا في البيئة يستدعي مفسرًا لم يعد موجودًا. إعادة تشغيل التنشيط أو إعادة تسمية البيئة لا يصلح هذه المسارات المضمنة بشكل موثوق؛ الحل الموثق في بايثون هو إعادة إنشاء البيئة في موقعها الجديد. بايثون: venv وكيفية عمل البيئات

1. افتح المشروع المنقول في مبنى الأوامر (Terminal)

في Terminal، انتقل إلى الدليل الحالي للمشروع. في zsh أو bash، ضع المسار بين علامتي اقتباس إذا كان يحتوي على مسافات أو أحرف خاصة بـ shell؛ واستبدل مسار المثال بموقع المجلد الفعلي:

cd "$HOME/Projects/My Python Project"
pwd
ls -la

تأكد من أنك في جذر المشروع ويمكنك رؤية ملفات المصدر ومعلومات التبعيات الخاصة به. تتضمن سجلات التبعيات الشائعة requirements.txt وpyproject.toml وملف قفل خاص بالمشروع. لا تحذف المشروع بأكمله أو ملفات تبعياته. إذا لم تكن متأكدًا من الدليل الذي يمثل البيئة القديمة، فافحص محتوياته قبل إزالة أي شيء.

2. أزل البيئة القديمة فقط

إذا كان دليل البيئة يحمل الاسم .venv ويقع داخل جذر المشروع، فاحذف هذا الدليل وحده. قم أولاً بإلغاء تنشيطه إذا كان سطر أوامر shell يوضح أنه نشط؛ deactivate هو أمر shell الموثق. ثم قم بتشغيل:

deactivate
rm -rf .venv

إذا لم تكن هناك بيئة نشطة، فقد يُفيد deactivate بأن الأمر غير متوفر؛ تابع دونه. قبل تشغيل rm -rf .venv، تحقق من أن pwd يعرض جذر المشروع وأن .venv هي البيئة التي تنوي استبدالها. إذا كانت بيئتك تستخدم اسمًا آخر أو تتواجد في مكان آخر، فاستبدلها بمسارها الدقيق وتجنب حذف كود المصدر أو بيانات المشروع. توصي بايثون بإزالة البيئة القديمة بعد إعادة إنشائها في موقعها الجديد؛ تزيلها هذه المقالة أولاً لتجنب أي لبس في الهدف المقصود. بايثون: venv وكيفية عمل البيئات

3. أعد إنشاء البيئة باستخدام إصدار بايثون المطلوب

إذا كان المشروع يحدد إصدار بايثون، فاستخدم مفسرًا مطابقًا متوفرًا على جهاز Mac الخاص بك. على سبيل المثال، عندما يكون python3.12 مثبتًا ويتطلب المشروع هذا الإصدار:

python3.12 -m venv .venv
source .venv/bin/activate
python --version
python -m pip --version

إذا لم يحدد المشروع إصدارًا وكان python3 المعتاد لديك مناسبًا، فاستخدم python3 -m venv .venv بدلاً من ذلك. على نظام macOS، أمر التنشيط القياسي لـ zsh وbash هو source .venv/bin/activate. تحقق من ناتج python --version قبل استعادة الحزم؛ يجب أن يشير python إلى مفسر البيئة بمجرد تنشيطها. بايثون: تنشيط venv ومسارات المفسر

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

4. أعد تثبيت التبعيات من المشروع

استخدم تعليمات التبعيات الحالية للمشروع أو ملف القفل عند توفره. بالنسبة لمشروع يتتبع التبعيات في requirements.txt، أعد تثبيتها باستخدام بايثون وpip الخاصين بالبيئة:

python -m pip install -r requirements.txt

استخدام python -m pip يربط pip بالمفسر الذي يحدده python. إذا كان المشروع يستخدم مدير تبعيات آخر أو ملف قفل، فاتبع إجراء التثبيت الموثق لتلك الأداة بدلاً من اختراع ملف requirements أو تجاهل ملف القفل. تتضمن بيئة venv الجديدة pip افتراضيًا، وتقدم وثائق بايثون تحديدًا ملف requirements كطريقة لإعادة إنشاء الحزم المثبتة. بايثون: venv، بايثون: تثبيت وحدات بايثون

إذا فشل التثبيت لأن حزمة ما تحتاج إلى مصرف (compiler) أو مكتبة أصلية أو إصدار بايثون لا يدعمه المشروع، فقد تكون البيئة الافتراضية نفسها قد أُعيد إنشاؤها بشكل صحيح بينما لا تزال تلك التبعية بحاجة إلى متطلباتها المسبقة الموثقة. اقرأ إرشادات التثبيت الخاصة بالحزمة أو المشروع وعالج الخطأ المحدد؛ لا تتعامل مع المشكلة باستخدام sudo pip أو تغيير ملكية ملفات بايثون الخاصة بالنظام. تنصح Homebrew بعدم استخدام هذه الحلول البديلة للأدلة المدارة. Homebrew: بيئات تشغيل اللغات والحزم

5. تحقق من أن البيئة التي تم إصلاحها نشطة

تأكد من أن المفسر المحدد موجود داخل مجلد .venv الجديد، ثم قم بتشغيل الأمر العادي للمشروع أو تعليمات الاختبار:

python -c 'import sys; print(sys.executable)'

يجب أن يشير المسار المطبوع إلى داخل دليل .venv الخاص بالمشروع. إذا كان يشير إلى مكان آخر، فقم بتنشيط البيئة من جذر المشروع مرة أخرى وتحقق من إعدادات بدء تشغيل shell أو الأسماء المستعارة للأوامر (aliases) التي تغير اختيار بايثون. يؤكد هذا الفحص اختيار المفسر؛ لكنه لا يثبت أن كل تبعيات المشروع أو ميزات التطبيق تعمل.

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

المصادر