البيئات الافتراضية في بايثون: venv و requirements.txt

المشكلة التي تحلّها البيئة الافتراضية في بايثون

عند تثبيت بايثون وتشغيل pip install requests، تُوضع الحزمة في مكان عام واحد على الجهاز. هذا مقبول لمشروع واحد، لكن مع المشروع الثالث تبدأ المشاكل بالظهور:

• المشروع (أ) يحتاج django==3.2، والمشروع (ب) يحتاج django==5.0. لا يمكن تثبيت أكثر من إصدار واحد بشكل عام على نفس الجهاز.
• تريد تجربة مكتبة جديدة دون أن تلوّث باقي المشاريع على جهازك.
• يستنسخ زميلك في الفريق المستودع ولا يعرف ما هي الإصدارات التي اعتمدت عليها فعلاً.

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

إنشاء بيئة افتراضية بايثون باستخدام venv

الأداة venv تأتي مدمجة مع بايثون 3، فلا تحتاج إلى تثبيت أي شيء إضافي. من داخل مجلد مشروعك نفّذ:

python3 -m venv .venv

ينشئ هذا الأمر مجلد .venv/ بجانب ملفات الكود. تسمية .venv أصبحت الأكثر شيوعًا تقريبًا في مشاريع بايثون؛ فالنقطة في بدايته تُخفيه من معظم قوائم الملفات، كما أن المحررات مثل VS Code تكتشفه تلقائيًا.

بعد انتهاء الأمر، يحتوي المجلد على نسخة كاملة من بايثون (بحجم عشرات الميغابايتات، وهذا أمر طبيعي) بالإضافة إلى نسخة pip خاصة به.

تفعيل البيئة الافتراضية

عند التفعيل، يُعاد ضبط متغير PATH في الطرفية بحيث يشير python و pip إلى النسختين الموجودتين داخل .venv/. ويختلف الأمر المستخدم بحسب نظام التشغيل:

# macOS / Linux
source .venv/bin/activate

# Windows (Command Prompt)
.venv\Scripts\activate.bat

# Windows (PowerShell)
.venv\Scripts\Activate.ps1

حينما تكون البيئة مفعّلة، سيظهر أمام سطر الأوامر لديك البادئة (.venv) كإشارة بصرية تذكّرك بذلك. أي أمر pip install تنفّذه الآن سيؤثر على هذا المشروع فقط.

وعند انتهائك من العمل، يكفي تنفيذ الأمر deactivate لإعادة الأمور إلى ما كانت عليه:

deactivate

لا داعي لإلغاء تفعيل البيئة قبل إغلاق الطرفية، فبمجرد إنهاء الجلسة يتم إلغاء التفعيل تلقائياً.

تثبيت الحزم في بايثون

بعد تفعيل البيئة الافتراضية، ثبّت الحزم التي تحتاجها:

pip install requests
pip install "pandas>=2.0"
pip install --upgrade requests

للاطلاع على ما هو مثبّت لديك، استخدم pip list، ولحذف حزمة معيّنة نفّذ pip uninstall requests.

تُخزَّن الحزم المثبَّتة داخل المجلد .venv/lib/pythonX.Y/site-packages/، ولا يُفترض بك أبداً تعديل محتوياته يدوياً، فإدارة هذا المجلد تقع على عاتق pip وحده.

تثبيت إصدارات الاعتماديات عبر requirements.txt

مشروعك لن يكون قابلاً لإعادة الإنتاج إلا إذا تمكّن الآخرون من تثبيت نفس الإصدارات التي استعملتَها. وأبسط طريقة لتوثيق ذلك هي ملف requirements.txt:

pip freeze > requirements.txt

يعرض الأمر pip freeze جميع الحزم المثبّتة مع رقم الإصدار الدقيق لكل واحدة. احفظ هذا الملف في git وارفعه مع المشروع.

وعندما يستنسخ أحد زملائك المستودع (أو حتى أنت لاحقًا على جهاز جديد):

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

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

إعداد نموذجي لمشروع بايثون

سير العمل الكامل من البداية إلى النهاية:

# Create the project folder
mkdir my_tool && cd my_tool

# Create and activate the venv
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install requests rich

# Save them
pip freeze > requirements.txt

# Work on your code...
echo "import requests; print(requests.__version__)" > main.py
python main.py

# When you're done
deactivate

أضف .venv إلى ملف .gitignore

لا ترفع أبدًا مجلد .venv/ إلى المستودع، فهو مرتبط بنظام التشغيل ويمكن إعادة إنشائه بسهولة من ملف requirements.txt:

# .gitignore
.venv/
__pycache__/
*.pyc

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

أي إصدار من بايثون تستخدم؟

افتراضيًا، يستخدم الأمر python3 -m venv .venv أي python3 تتعرّف عليه الصدفة (shell) لديك. وإذا كان مثبتًا عندك أكثر من إصدار (مثلًا 3.12 و 3.13)، فمن الأفضل أن تحدد الإصدار المطلوب صراحةً:

python3.13 -m venv .venv

بمجرّد إنشاء البيئة الافتراضية، يصبح مُفسِّر بايثون الخاص بها مثبَّتًا عليها — أي أنّ تشغيل python داخل البيئة المُفعَّلة سيستخدم دائمًا تلك النسخة المحددة، حتى لو تغيّرت نسخة بايثون على نظامك.

حلول المشاكل الشائعة

إليك بعض الأعراض المتكرّرة وطرق حلّها:

• pip install يعمل، لكن الاستيراد يفشل. معنى ذلك أنّك ثبّتت الحزم على نسخة بايثون خاطئة. فعِّل البيئة الافتراضية قبل pip install، ثم تأكّد بالأمر which python (على macOS/Linux) أو where python (على Windows).
• ظهور ModuleNotFoundError بعد التفعيل. إمّا أنّ البيئة أُنشئت دون المكتبات المطلوبة، أو أنّ الحزمة ثُبِّتت في بيئة افتراضية أخرى. الأمر pip list يُظهر ما هو مُثبَّت فعليًّا في البيئة الحالية.
• سكربت التفعيل غير موجود على Windows. قد يمنع PowerShell تشغيل السكربتات غير الموقَّعة. نفِّذ الأمر التالي مرّة واحدة للسماح بالسكربتات المحلية: Set-ExecutionPolicy -Scope CurrentUser RemoteSigned.
• الخطأ No module named venv. في بعض توزيعات لينكس، تأتي venv كحزمة منفصلة. على Debian/Ubuntu استخدم: sudo apt install python3-venv.

ما بعد venv: Poetry و uv و pipenv

بعد أن تعتاد على الثلاثي venv + pip + requirements.txt، ستصادف أدوات تغلِّف الفكرة نفسها لكن بتجربة استخدام أفضل:

• Poetry — يُدير البيئات الافتراضية والاعتماديات والتغليف عبر ملفّ واحد هو pyproject.toml.
• uv — بديل سريع جدًّا لـ pip، ويتعامل أيضًا مع البيئات الافتراضية.
• pipenv — أداة أقدم شاعت بفضل نمط Pipfile + Pipfile.lock.

كلّها أدوات جيّدة، ولا يشترط أيّ منها في مرحلة التعلّم. أتقِن أوّلًا سير العمل البسيط مع venv، وما تبقّى مجرّد تحسينات.

الخلاصة

• كلّ مشروع بايثون حقيقي يستحقّ بيئة افتراضية خاصّة به.
• أنشئها بالأمر python3 -m venv .venv، ثم فعِّلها، وبعدها ثبِّت الحزم بكلّ حرية عبر pip install.
• ثبِّت الاعتماديات بأمر pip freeze > requirements.txt واحفظ هذا الملفّ في Git.
• لا تُضِف مجلّد .venv/ نفسه إلى المستودع أبدًا.
• عند حدوث مشاكل في الاستيراد، ابدأ بالتحقّق من نسخة بايثون المُفعَّلة حاليًّا.

ما يلي: نمط __main__

بعد أن صار لديك مشروع مُجهَّز وحزم مثبَّتة، يبقى اصطلاح أخير يُختتم به هذا الفصل — وهو الحارس if __name__ == "__main__". تجده تقريبًا في كلّ ملفّ بايثون مُعَدّ للتشغيل كسكربت، وسيكون موضوع الصفحة التالية.