البيئة الافتراضية venv في بايثون تعزل مكتبات كل مشروع عن المشاريع الأخرى، بحيث يمكنك استخدام إصدارات مختلفة من الحزم بدون أن تؤثر على بقية مشاريعك.
لإنشاء بيئة افتراضية تستخدم عادةً python -m venv venv، ثم تفعّلها على Windows أو macOS أو Linux وتثبت مكتبات المشروع داخلها باستخدام pip. وعند مشاركة المشروع، لا ترفع مجلد البيئة نفسه؛ بل تحفظ المتطلبات في ملف requirements.txt ليتمكن الآخرون من إعادة إنشاء البيئة.
في هذا الدليل ستتعلم لماذا نستخدم venv، وكيف تنشئها وتفعّلها، وكيف تتأكد أن python وpip يشيران إلى البيئة الصحيحة، مع أشهر الأخطاء التي تواجه المبتدئين أثناء العمل على مشروع حقيقي.
الفكرة ببساطة: البيئة الافتراضية تجعل لكل مشروع مكتباته الخاصة، بدل أن تختلط مكتبات كل المشاريع مع بعض. {alertInfo}
{getToc} $title={محتوى المقال}
إنشاء وتفعيل venv بسرعة
إذا كنت تريد الأوامر مباشرة، افتح الطرفية داخل مجلد مشروعك ثم أنشئ البيئة الافتراضية:
python -m venv .venvبعدها فعّلها بالأمر المناسب للطرفية التي تستخدمها:
| النظام أو الطرفية | أمر التفعيل |
|---|---|
| Windows - Command Prompt | .venv\Scripts\activate.bat |
| Windows - PowerShell | .\.venv\Scripts\Activate.ps1 |
| macOS / Linux | source .venv/bin/activate |
بعد التفعيل ثبت مكتبات مشروعك باستخدام python -m pip install ...، وعند الانتهاء اكتب deactivate. ستجد شرح كل خطوة والمشاكل الشائعة بالتفصيل في الأقسام التالية.
ما هي البيئة الافتراضية venv في Python؟
البيئة الافتراضية venv هي بيئة معزولة لها مفسر بايثون ومسارات تثبيت حزم خاصة بها. عند استخدام مفسر هذه البيئة، تُثبّت الحزم داخلها بدل أن تختلط بحزم المشاريع الأخرى أو ببيئة بايثون العامة.
بمعنى أبسط: بدل أن تجعل كل مشاريعك تعتمد على مجموعة واحدة من المكتبات والإصدارات، تمنح كل مشروع بيئة يمكن حذفها وإعادة إنشائها عند الحاجة.
مثال:
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؟
نعم، venv جزء من مكتبة بايثون القياسية، لذلك لا تثبتها باستخدام pip. لكن بعض توزيعات Linux تفصل دعمها في حزمة نظام مستقلة؛ فإذا فشل python3 -m venv برسالة أن الوحدة غير متاحة، قد تحتاج إلى تثبيت حزمة مثل python3-venv من مدير حزم النظام.
يمكنك التحقق من إصدار Python لديك بالأمر:
python --versionأو في بعض الأجهزة:
python3 --versionما الفرق بين venv و virtualenv؟
كلاهما ينشئ بيئات بايثون معزولة، لكن venv يأتي ضمن Python الحديثة ولا يحتاج عادةً إلى تثبيت حزمة خارجية، بينما virtualenv أداة مستقلة تُثبت بصورة منفصلة وتوفر خيارات إضافية لبعض الاستخدامات.
| الأداة | تأتي مع Python؟ | متى أستخدمها؟ |
|---|---|---|
venv | نعم في Python الحديثة | الخيار الأبسط لمعظم مشاريع Python 3 والمبتدئين. |
virtualenv | لا، تُثبت كحزمة مستقلة | عندما تحتاج خصائص إضافية أو تعمل ضمن إعدادات خاصة. |
إذا كنت تتعلم Python 3 الآن، ابدأ بـvenv. لا تحتاج إلى الانتقال إلى virtualenv لمجرد إنشاء بيئة مستقلة لمشروع عادي.
الخطوة الأولى: افتح مجلد المشروع
قبل إنشاء البيئة الافتراضية، افتح الطرفية داخل مجلد المشروع. مثلًا إذا كان مشروعك اسمه 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.batوإذا كنت تستخدم PowerShell:
.\venv\Scripts\Activate.ps1تفعيل venv على macOS و Linux
source venv/bin/activate
بعد التفعيل، غالبًا ستظهر كلمة (venv) في بداية سطر الطرفية:
(venv) my_project>هذا مؤشر شائع على أن البيئة مفعّلة، لكن الاختبار الأدق هو معرفة مفسر بايثون المستخدم:
python -c "import sys; print(sys.executable)"
يجب أن يشير المسار إلى مجلد البيئة مثل venv أو .venv. ومن المهم أيضًا أن تعرف أن تفعيل البيئة ليس شرطًا تقنيًا لتشغيلها؛ التفعيل يضيف مسارها إلى PATH لتسهيل استخدام python وpip. ويمكنك تشغيل مفسر البيئة مباشرة إذا استخدمت مساره الكامل.
كيف أعرف أن venv مفعّلة فعلًا؟
ظهور (venv) أو (.venv) في بداية الطرفية علامة مفيدة، لكن يمكنك التأكد بصورة أدق من مسار مفسر Python الحالي:
python -c "import sys; print(sys.executable)"إذا كان المسار يشير إلى venv\Scripts\python.exe على Windows أو venv/bin/python على macOS/Linux، فأنت تستخدم مفسر البيئة.
ويمكنك أيضًا فحص متغير VIRTUAL_ENV:
echo %VIRTUAL_ENV%الأمر السابق لـCommand Prompt على Windows. في PowerShell استخدم:
echo $Env:VIRTUAL_ENVوفي macOS أو Linux:
echo $VIRTUAL_ENVإذا أعاد المتغير مسار البيئة، فهذا مؤشر إضافي على أنها مفعّلة. ومع ذلك يبقى sys.executable اختبارًا مباشرًا لمعرفة أي مفسر يشغّل أوامرك حاليًا.
مشكلة PowerShell عند تفعيل venv
في بعض أجهزة Windows قد تظهر رسالة مثل Activate.ps1 cannot be loaded because running scripts is disabled on this system. هذه المشكلة مرتبطة بسياسة تشغيل سكربتات PowerShell، وليست دليلًا على أن venv نفسها تالفة.
أبسط حل للمبتدئ هو فتح Command Prompt وتشغيل ملف التفعيل الخاص به:
venv\Scripts\activate.batإذا كنت تحتاج PowerShell تحديدًا، يمكنك السماح بالتشغيل للجلسة الحالية فقط ثم إعادة محاولة التفعيل:
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypassثم:
.\venv\Scripts\Activate.ps1تنبيه: لا تغيّر سياسة تشغيل PowerShell بشكل دائم لمجرد تفعيل venv إذا لم تكن تعرف أثر الإعداد. استخدام Scope Process يقتصر على نافذة PowerShell الحالية، أو استخدم Command Prompt بدلًا من تغيير إعدادات دائمة. {alertInfo}
الخطوة الرابعة: تثبيت مكتبة داخل البيئة الافتراضية
بعد تفعيل البيئة، ثبت المكتبة التي تحتاجها. مثلًا:
python -m pip install requests
الآن مكتبة requests تُثبّت داخل بيئة المشروع. واستخدام python -m pip مفيد لأنه يشغّل pip من نفس مفسر بايثون الحالي. إذا أردت شرح التثبيت بالتفصيل، راجع شرح pip في بايثون وتثبيت المكتبات.
يمكنك التأكد من المكتبات المثبتة بالأمر:
python -m pip listماذا أفعل إذا كان pip غير موجود داخل venv؟
ابدأ بالتحقق من pip من خلال مفسر البيئة نفسه بدل الاعتماد على أمر pip المختصر:
python -m pip --versionإذا نجح هذا الأمر، استخدم دائمًا python -m pip install package_name. أما إذا ظهرت رسالة No module named pip داخل البيئة، فيمكن محاولة تجهيز pip باستخدام:
python -m ensurepip --upgradeإذا كانت البيئة أُنشئت بصورة غير سليمة، يكون حذفها وإعادة إنشائها من مفسر Python الصحيح حلًا أنظف من إصلاح ملفات البيئة يدويًا.
مثال عملي: مشروع يستخدم 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
سيتم إنشاء ملف يحتوي الحزم وإصداراتها الموجودة داخل البيئة. يختلف المحتوى حسب ما ثبّتَّه؛ فإذا ثبتت requests مثلًا فسيظهر سطر لها مع رقم الإصدار المثبت، إلى جانب اعتمادياتها.
requests==2.34.2
لا تعتمد على رقم الإصدار في المثال عند إنشاء مشروعك؛ استخدم ناتج pip freeze من بيئتك الفعلية. هذا الملف هو الذي ترفعه إلى 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. البيئة الافتراضية قابلة لإعادة الإنشاء ولا يُنصح بنقلها أو نسخها بين الأجهزة كما هي. وإذا أردت بداية منظمة لمجلدات مشروعك، يمكنك استخدام مولد هيكل مشاريع بايثون.
وعندما تصل إلى مرحلة تحويل تطبيق ويندوز إلى ملف تنفيذي، يفيدك إنشاء بيئة نظيفة للمشروع قبل البناء؛ راجع تحويل ملف بايثون إلى EXE باستخدام PyInstaller.
كيف أوقف تفعيل البيئة الافتراضية؟
إذا أردت الخروج من البيئة الافتراضية، استخدم:
deactivate
بعدها تختفي كلمة (venv) من بداية سطر الطرفية.
كيف أحذف البيئة الافتراضية venv؟
البيئة الافتراضية عبارة عن مجلد يمكن إعادة إنشائه. إذا لم تعد تحتاجها، أوقف التفعيل أولًا باستخدام deactivate ثم احذف مجلد venv أو .venv.
يمكنك حذف المجلد يدويًا من مدير الملفات، أو من Command Prompt على Windows:
rmdir /s /q venvوفي macOS أو Linux:
rm -rf venvتحذير: أوامر حذف المجلدات نهائية. تأكد أنك داخل مجلد المشروع وأن الاسم هو مجلد البيئة فعلًا قبل تنفيذ الأمر. وجود requirements.txt يسمح لك بإعادة إنشاء البيئة وتثبيت المكتبات لاحقًا. {alertWarning}
كيف أستخدم مشروعًا يحتوي 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 لأن المكتبة مثبتة داخل البيئة، لكنك تشغل المشروع بمفسر آخر خارجها. إذا استمر الخطأ، راجع حل خطأ ModuleNotFoundError: No module named في بايثون.
5. حذف venv بدون وجود requirements.txt
إذا حذفت البيئة ولم تحفظ المتطلبات، ستحتاج إلى تذكر المكتبات يدويًا. لذلك أنشئ requirements.txt دائمًا عند استخدام مكتبات خارجية.
قائمة فحص لاستخدام venv في مشروع Python
| السؤال | نعم أم لا؟ |
|---|---|
| هل أنشأت البيئة داخل مجلد المشروع؟ | |
| هل فعلت البيئة قبل تثبيت المكتبات؟ | |
هل ظهر (venv) في الطرفية؟ |
|
| هل ثبتت المكتبات داخل البيئة؟ | |
هل أنشأت requirements.txt؟ |
|
هل أضفت venv/ إلى .gitignore؟ |
|
| هل كتبت طريقة التثبيت في README؟ |
مصادر خارجية مفيدة للتوسع
- توثيق 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 حتى تستطيع تثبيت المكتبات مرة أخرى بسهولة.
هل venv هي نفسها virtualenv؟
الهدف متشابه: إنشاء بيئة Python معزولة. لكن venv تأتي ضمن Python الحديثة، بينما virtualenv أداة مستقلة تُثبت بصورة منفصلة وتوفر خيارات إضافية لبعض الحالات.
ماذا أفعل إذا كان أمر pip لا يعمل داخل venv؟
جرّب python -m pip --version أولًا. إذا نجح، استخدم python -m pip بدل الأمر المختصر. وإذا ظهر No module named pip، جرّب python -m ensurepip --upgrade أو أعد إنشاء البيئة من مفسر Python الصحيح.