يأتي Ubuntu 24.04 مع Python 3.12، لكن تثبيت الحزم باستخدام pip مباشرةً يفشل الآن برسالة «externally-managed-environment». الحل هو عزل كل مشروع في بيئة افتراضية خاصة به. يوضح هذا الدليل كيف تجهّز VPS Linux Infrawire، وتدير الاعتماديات بشكل سليم، وتُبقي التطبيق يعمل كخدمة systemd.
📋 المتطلبات المسبقة
- خادم VPS بنظام Ubuntu 24.04 أو Debian 12 مع وصول SSH بصلاحيات root (عنوان IP وكلمة مرور root متاحان في منطقة العميل)
- مشروع بايثون أو سكربت بسيط للتجربة
- معرفة أساسية بسطر الأوامر
1. تثبيت Python 3 وpip وvenv
عادةً ما يكون Python 3 مثبّتًا مسبقًا، لكن pip ووحدة venv حزمتان منفصلتان.
Bashapt update apt install -y python3 python3-pip python3-venv python3-dev build-essential python3 --version pip3 --version
2. فهم خطأ PEP 668
تشغيل pip install requests بصلاحيات root على Ubuntu 24.04 أو Debian 12 يعرض:
TEXTerror: externally-managed-environment
تمنع هذه الحماية (PEP 668) برنامج pip من الكتابة فوق ملفات يديرها apt وإتلاف أدوات النظام. لا تتجاوزها بالخيار --break-system-packages، بل استخدم إحدى الطرق النظيفة الثلاث التالية.
3. إنشاء بيئة افتراضية
البيئة الافتراضية نسخة خاصة من Python وpip لمشروع واحد.
Bashmkdir -p /opt/myapp && cd /opt/myapp python3 -m venv venv source venv/bin/activate pip install --upgrade pip pip install requests flask gunicorn
يبدأ الموجّه الآن بـ (venv). اخرج من البيئة بالأمر deactivate.
4. إدارة الاعتماديات عبر requirements.txt
ثبّت الإصدارات بدقة لتتمكن من إعادة بناء المشروع بالشكل نفسه على خادم آخر.
Bashpip freeze > requirements.txt # على جهاز جديد python3 -m venv venv source venv/bin/activate pip install -r requirements.txt
5. تثبيت أدوات سطر الأوامر باستخدام pipx
للأدوات المستقلة (httpie وyt-dlp وblack وغيرها) يمنح pipx كل أداة بيئتها الافتراضية المخفية ويتيح الأمر على مستوى النظام.
Bashapt install -y pipx pipx ensurepath pipx install httpie
افتح جلسة صدفة جديدة بعد ذلك ليُحمَّل PATH المحدَّث. أما المكتبة التي لها حزمة Debian فيصلح أيضًا apt install python3-requests.
6. تشغيل التطبيق كخدمة systemd
أنشئ مستخدمًا مخصصًا بلا صلاحيات، ثم وحدة تشغّل مفسّر البيئة الافتراضية (هنا Gunicorn يخدم كائن Flask باسم app في الملف app.py).
Bashuseradd --system --home /opt/myapp --shell /usr/sbin/nologin myapp chown -R myapp:myapp /opt/myapp
أنشئ الملف /etc/systemd/system/myapp.service:
INI1[Unit] 2Description=My Python application 3After=network.target 4 5[Service] 6User=myapp 7WorkingDirectory=/opt/myapp 8ExecStart=/opt/myapp/venv/bin/gunicorn --bind 127.0.0.1:8000 app:app 9Restart=on-failure 10RestartSec=5 11 12[Install] 13WantedBy=multi-user.target
Bashsystemctl daemon-reload systemctl enable --now myapp
ضع وكيلًا عكسيًا مثل nginx أمام المنفذ 8000 لإتاحة التطبيق على الإنترنت.
✅ التحقق
Bashwhich python # يجب أن يشير إلى داخل /opt/myapp/venv عند التفعيل pip list systemctl status myapp --no-pager journalctl -u myapp -n 50 --no-pager curl -I http://127.0.0.1:8000
🔧 استكشاف الأخطاء وإصلاحها
The virtual environment was not created successfully because ensurepip is not available : حزمة venv غير مثبّتة. ثبّتها بالأمر apt install python3-venv (أو python3.12-venv) وأعد تنفيذ الأمر.
status=203/EXEC في systemd : المسار في ExecStart خاطئ أو أن الملف غير قابل للتنفيذ من مستخدم الخدمة. تحقق بالأمر ls -l /opt/myapp/venv/bin/gunicorn ومن الملكية التي حددتها سابقًا.
ModuleNotFoundError تحت systemd فقط : تستخدم الخدمة بايثون النظام بدل البيئة الافتراضية. استدعِ دائمًا /opt/myapp/venv/bin/python أو الملف التنفيذي داخل venv/bin في ExecStart.
pip: command not found : استخدم python3 -m pip أو فعّل البيئة الافتراضية أولًا.
🎉 أصبحت مشاريع بايثون لديك معزولة وقابلة للتكرار وتعمل كخدمة موثوقة!