عندما تبدأ في تعلم Python، قد تثبت مكتبة لمشروع معين، ثم بعد فترة تعمل على مشروع آخر يحتاج إصدارًا مختلفًا من نفس المكتبة. هنا قد تظهر مشاكل غريبة: مشروع يعمل، ومشروع آخر يتوقف، أو مكتبة تتحدث وتكسر كودًا قديمًا.
الحل البسيط لهذه المشكلة هو استخدام البيئة الافتراضية أو venv. في هذا الدرس من بايثون العرب سنشرح ما معنى البيئة الافتراضية في Python، ولماذا نستخدمها، وكيف ننشئها ونفعلها على Windows و macOS و Linux، ثم كيف نثبت المكتبات داخلها ونربطها بملف requirements.txt.
{getToc} $title={محتوى المقال}
الفكرة ببساطة: البيئة الافتراضية تجعل لكل مشروع مكتباته الخاصة، بدل أن تختلط مكتبات كل المشاريع مع بعض. {alertInfo}
ما هي البيئة الافتراضية venv في Python؟
البيئة الافتراضية venv هي مجلد خاص داخل مشروع Python يحتوي نسخة مستقلة من أدوات التشغيل والمكتبات المثبتة للمشروع. عندما تفعل هذه البيئة، فإن المكتبات التي تثبتها باستخدام pip تكون خاصة بهذا المشروع فقط.
بمعنى أبسط: بدل أن تثبت كل مكتبات Python في مكان واحد عام على جهازك، تجعل لكل مشروع مساحة منفصلة لمكتباته.
مثال:
project_one/
└── venv/
project_two/
└── venv/كل مشروع هنا لديه بيئته الخاصة. إذا ثبتت مكتبة داخل المشروع الأول، لن تؤثر على المشروع الثاني.
لماذا نحتاج venv في مشاريع Python؟
استخدام venv ليس شيئًا متقدمًا فقط، بل عادة مهمة حتى للمبتدئين عندما يبدأون ببناء مشاريع تستخدم مكتبات خارجية.
نحتاج البيئة الافتراضية لأنها تساعدنا على:
- عزل مكتبات كل مشروع عن المشاريع الأخرى.
- تجنب تعارض إصدارات المكتبات.
- تنظيم المشروع عند رفعه إلى GitHub.
- إنشاء ملف
requirements.txtنظيف. - تجربة مكتبات جديدة بدون تخريب بيئة Python العامة.
- تشغيل المشروع لاحقًا بنفس المتطلبات تقريبًا.
نصيحة للمبتدئ: إذا كان مشروعك يستخدم مكتبات خارجية مثلrequestsأوflaskأوpandas، استخدم بيئة افتراضية من البداية. {alertSuccess}
مثال بسيط يوضح المشكلة بدون venv
تخيل أن لديك مشروعين:
- مشروع قديم يحتاج إصدارًا معينًا من مكتبة.
- مشروع جديد يحتاج إصدارًا أحدث من نفس المكتبة.
إذا ثبتت كل شيء في بيئة عامة واحدة، قد يتأثر المشروع القديم بعد تحديث المكتبة. أما مع venv، كل مشروع يحتفظ بإصداراته الخاصة.
| بدون venv | مع venv |
|---|---|
| كل المشاريع تشارك نفس المكتبات. | كل مشروع له مكتباته الخاصة. |
| احتمال تعارض الإصدارات أكبر. | تعارض الإصدارات أقل. |
| يصعب معرفة متطلبات كل مشروع. | يسهل إنشاء requirements.txt لكل مشروع. |
| قد تثبت مكتبات كثيرة لا تحتاجها. | تثبت فقط ما يحتاجه المشروع. |
هل venv يأتي مع Python؟
نعم، في الإصدارات الحديثة من Python تأتي وحدة venv ضمن المكتبة القياسية، ويمكن استخدامها مباشرة بدون تثبيت مكتبة خارجية.
يمكنك التحقق من إصدار Python لديك بالأمر:
python --versionأو في بعض الأجهزة:
python3 --versionالخطوة الأولى: افتح مجلد المشروع
قبل إنشاء البيئة الافتراضية، افتح الطرفية داخل مجلد المشروع. مثلًا إذا كان مشروعك اسمه my_project:
my_project/
└── main.pyافتح الطرفية داخل هذا المجلد، ثم أنشئ البيئة الافتراضية.
الخطوة الثانية: إنشاء بيئة افتراضية venv
لإنشاء بيئة افتراضية باسم venv، استخدم الأمر التالي:
python -m venv venvفي بعض الأجهزة، خصوصًا macOS أو Linux، قد تحتاج إلى:
python3 -m venv venv
بعد تنفيذ الأمر، سيظهر مجلد جديد داخل المشروع اسمه venv.
my_project/
│
├── main.py
└── venv/هذا المجلد يحتوي ملفات البيئة الافتراضية، ولا تحتاج إلى فتحه أو تعديل ملفاته يدويًا.
لماذا نكتب venv مرتين في الأمر؟
الأمر:
python -m venv venvيحتوي على كلمتين متشابهتين لكن معناهما مختلف:
| الجزء | معناه |
|---|---|
-m venv |
شغّل وحدة venv المسؤولة عن إنشاء البيئة الافتراضية. |
venv الأخيرة |
اسم المجلد الذي سيتم إنشاء البيئة داخله. |
يمكنك تسمية المجلد .venv بدل venv إذا أردت:
python -m venv .venv
لكن للمبتدئين، اسم venv واضح وسهل.
الخطوة الثالثة: تفعيل البيئة الافتراضية
بعد إنشاء البيئة، يجب تفعيلها حتى تصبح أوامر python و pip مرتبطة بهذه البيئة.
تفعيل venv على Windows
إذا كنت تستخدم Command Prompt:
venv\Scripts\activateوإذا كنت تستخدم PowerShell:
venv\Scripts\Activate.ps1تفعيل venv على macOS و Linux
source venv/bin/activate
بعد التفعيل، غالبًا ستظهر كلمة (venv) في بداية سطر الطرفية:
(venv) my_project>هذا يعني أن البيئة الافتراضية مفعّلة.
مشكلة PowerShell عند تفعيل venv
في بعض أجهزة Windows، قد تظهر رسالة منع تشغيل السكربتات عند استخدام PowerShell. إذا حدث ذلك، يمكنك استخدام Command Prompt بدل PowerShell، أو تعديل سياسة التشغيل في PowerShell بحذر.
للمبتدئين: إذا ظهرت لك مشكلة في PowerShell، افتح Command Prompt وجرب الأمر venv\Scripts\activate لأنه أبسط غالبًا. {alertInfo}
الخطوة الرابعة: تثبيت مكتبة داخل البيئة الافتراضية
بعد تفعيل البيئة، ثبت المكتبة التي تحتاجها. مثلًا:
python -m pip install requests
الآن مكتبة requests تثبت داخل بيئة المشروع، وليس في بيئة عامة مشتركة مع كل المشاريع.
يمكنك التأكد من المكتبات المثبتة بالأمر:
python -m pip listمثال عملي: مشروع يستخدم requests داخل venv
لننشئ ملف main.py يحتوي هذا المثال:
import requests
response = requests.get("https://example.com")
print("Status code:", response.status_code)لتشغيل المشروع بعد تفعيل البيئة:
python main.py
إذا كانت مكتبة requests مثبتة داخل البيئة، سيعمل البرنامج بدون مشكلة.
الخطوة الخامسة: إنشاء requirements.txt من venv
بعد تثبيت مكتبات المشروع داخل البيئة، أنشئ ملف requirements.txt:
python -m pip freeze > requirements.txtسيتم إنشاء ملف يحتوي المكتبات المطلوبة. مثال:
certifi==2024.2.2
charset-normalizer==3.3.2
idna==3.6
requests==2.31.0
urllib3==2.2.1
هذا الملف هو الذي ترفعه إلى GitHub بدل رفع مجلد venv.
هل أرفع مجلد venv إلى GitHub؟
لا، غالبًا لا ترفع مجلد venv إلى GitHub. السبب أنه كبير، ويحتوي ملفات خاصة بجهازك، ويمكن لأي شخص إنشاؤه من جديد وتثبيت المتطلبات من requirements.txt.
بدل رفع venv، أضفه إلى ملف .gitignore:
venv/
.venv/تحذير مهم: لا ترفع مجلدvenvإلى GitHub. ارفعrequirements.txtفقط حتى يعرف الآخرون المكتبات المطلوبة. {alertWarning}
شكل مشروع Python منظم مع venv
داخل جهازك قد يكون شكل المشروع هكذا:
my_project/
│
├── main.py
├── README.md
├── requirements.txt
├── .gitignore
└── venv/
لكن على GitHub يجب ألا يظهر مجلد venv إذا كان موجودًا في .gitignore.
كيف أوقف تفعيل البيئة الافتراضية؟
إذا أردت الخروج من البيئة الافتراضية، استخدم:
deactivate
بعدها تختفي كلمة (venv) من بداية سطر الطرفية.
كيف أستخدم مشروعًا يحتوي requirements.txt؟
إذا حملت مشروعًا من GitHub وفيه requirements.txt، يمكنك تشغيله بهذا الترتيب:
- افتح مجلد المشروع.
- أنشئ بيئة افتراضية.
- فعّل البيئة.
- ثبت المكتبات من
requirements.txt. - شغّل المشروع.
الأوامر:
python -m venv venv
venv\Scripts\activate
python -m pip install -r requirements.txt
python main.pyعلى macOS و Linux:
python3 -m venv venv
source venv/bin/activate
python -m pip install -r requirements.txt
python main.pyما الفرق بين venv و pip و requirements.txt؟
| العنصر | وظيفته | مثال |
|---|---|---|
venv |
ينشئ بيئة مستقلة للمشروع. | python -m venv venv |
pip |
يثبت المكتبات داخل البيئة. | python -m pip install requests |
requirements.txt |
يحفظ قائمة مكتبات المشروع. | python -m pip freeze > requirements.txt |
هذه الثلاثة تعمل معًا: تنشئ بيئة بـ venv، تثبت المكتبات بـ pip، ثم تحفظ القائمة في requirements.txt.
أخطاء شائعة عند استخدام venv في Python
1. تثبيت المكتبات قبل تفعيل البيئة
إذا نسيت تفعيل البيئة ثم ثبتت مكتبة، قد تثبت في مكان عام وليس داخل مشروعك. تأكد من ظهور (venv) قبل التثبيت.
2. رفع مجلد venv إلى GitHub
هذا خطأ شائع. لا ترفع venv. أضفه إلى .gitignore.
3. إنشاء requirements.txt من بيئة عامة
إذا لم تكن داخل البيئة الخاصة بالمشروع، قد يظهر ملف متطلبات مليء بمكتبات لا يحتاجها المشروع.
4. نسيان تفعيل البيئة قبل تشغيل المشروع
قد يظهر خطأ ModuleNotFoundError لأن المكتبة مثبتة داخل البيئة، لكنك تشغل المشروع خارجها.
5. حذف venv بدون وجود requirements.txt
إذا حذفت البيئة ولم تحفظ المتطلبات، ستحتاج إلى تذكر المكتبات يدويًا. لذلك أنشئ requirements.txt دائمًا عند استخدام مكتبات خارجية.
قائمة فحص لاستخدام venv في مشروع Python
| السؤال | نعم أم لا؟ |
|---|---|
| هل أنشأت البيئة داخل مجلد المشروع؟ | |
| هل فعلت البيئة قبل تثبيت المكتبات؟ | |
هل ظهر (venv) في الطرفية؟ |
|
| هل ثبتت المكتبات داخل البيئة؟ | |
هل أنشأت requirements.txt؟ |
|
هل أضفت venv/ إلى .gitignore؟ |
|
| هل كتبت طريقة التثبيت في README؟ |
روابط داخلية مفيدة من بايثون العرب
- كورس أساسيات بايثون للمبتدئين
- أفكار مشاريع بايثون للمبتدئين حسب المهارة
- شرح مكتبة pathlib في Python للتعامل مع مسارات الملفات
- مولد هيكل مشاريع بايثون
- قاموس بايثون
مصادر خارجية مفيدة للتوسع
- توثيق Python الرسمي حول البيئات الافتراضية
- توثيق مكتبة venv الرسمية في Python
- دليل Python Packaging حول pip والبيئات الافتراضية
الخلاصة
البيئة الافتراضية venv من أهم العادات التي يجب أن يتعلمها أي مبتدئ في Python عندما يبدأ ببناء مشاريع تستخدم مكتبات خارجية. فهي تساعدك على عزل مكتبات المشروع، وتجنب تعارض الإصدارات، وإنشاء ملف requirements.txt واضح.
ابدأ بإنشاء بيئة افتراضية داخل كل مشروع يحتاج مكتبات خارجية، فعّل البيئة قبل التثبيت والتشغيل، ولا ترفع مجلد venv إلى GitHub. ارفع بدلًا منه ملف requirements.txt، واكتب طريقة التثبيت داخل README.
الخلاصة العملية: استخدمvenvلكل مشروع مهم، وثبت المكتبات داخلها، ثم احفظ المتطلبات فيrequirements.txtولا ترفع مجلد البيئة إلى GitHub. {alertSuccess}
أسئلة شائعة مع إجاباتها
هل يجب استخدام venv في كل مشروع Python؟
ليس ضروريًا في التجارب الصغيرة التي لا تستخدم مكتبات خارجية، لكنه مهم جدًا في المشاريع التي تحتاج مكتبات مثبتة عبر pip.
هل أرفع مجلد venv إلى GitHub؟
لا. أضف venv/ إلى .gitignore وارفع requirements.txt بدلًا منه.
كيف أعرف أن venv مفعّلة؟
غالبًا ستظهر كلمة (venv) في بداية سطر الطرفية. يمكنك أيضًا استخدام python -m pip list لرؤية مكتبات البيئة الحالية.
ما الفرق بين venv و requirements.txt؟
venv هي البيئة التي تحتوي المكتبات فعليًا، أما requirements.txt فهو ملف نصي يحتوي أسماء المكتبات المطلوبة للمشروع.
ماذا أفعل إذا ظهرت ModuleNotFoundError رغم أنني ثبت المكتبة؟
تأكد أنك فعلت البيئة الافتراضية نفسها التي ثبتت المكتبة داخلها، ثم شغل المشروع بعد التفعيل.
هل يمكن حذف venv؟
نعم يمكن حذفها وإعادة إنشائها، لكن تأكد أن لديك requirements.txt حتى تستطيع تثبيت المكتبات مرة أخرى بسهولة.