حل أخطاء pip install في بايثون بالعربي

تكتب pip install requests، فيرد عليك الطرفية بخطأ. أغلب أخطاء pip تعود لسؤال واحد: في أي نسخة بايثون تحاول التثبيت؟ على جهازك غالبًا أكثر من نسخة: بايثون النظام، وبايثون ثبّتّه بنفسك، وربما بيئة افتراضية لمشروع قديم. وpip يثبّت في واحدة فقط منها.

الرسائل في هذا المقال منسوخة من تشغيل حقيقي على Ubuntu 24.04 مع pip 24 وpip 26، إلا رسائل ويندوز.

الوصفة التي تمنع أغلب هذه الأخطاء

قبل التفاصيل، هذه الأسطر الثلاثة هي ما يجب أن تفعله في كل مشروع:

python3 -m venv .venv            # مرة واحدة داخل مجلد المشروع (على ويندوز: py -m venv .venv)
source .venv/bin/activate        # لينكس / ماك
# .venv\Scripts\activate         # ويندوز

python -m pip install requests   # داخل البيئة المفعّلة

بعد التفعيل يظهر (.venv) في أول سطر الطرفية، ويصبح python وpip تابعين للبيئة. ولإلغاء التفعيل: deactivate.

1) pip غير موجود

على ويندوز (cmd):

'pip' is not recognized as an internal or external command,
operable program or batch file.

وعلى ماك أو لينكس:

zsh: command not found: pip

مجلد pip ليس في PATH، أو أن نظامك يسمّيه pip3. لا تطارد إعدادات PATH؛ استخدم pip من خلال بايثون نفسه:

python -m pip install requests     # أو python3 -m pip
py -m pip install requests         # ويندوز: py هو مشغّل بايثون الرسمي

إن قال لك حتى python إنه غير موجود على ويندوز، فأعد تشغيل مثبّت بايثون واختر Add python.exe to PATH، أو استخدم py الذي يُثبَّت معه.

2) externally-managed-environment

error: externally-managed-environment

× This environment is externally managed
╰─> To install Python packages system-wide, try apt install
    python3-xyz, where xyz is the package you are trying to
    install.

    If you wish to install a non-Debian-packaged Python package,
    create a virtual environment using python3 -m venv path/to/venv.
    ...
note: If you believe this is a mistake, please contact your Python installation
or OS distribution provider. You can override this, at the risk of breaking
your Python installation or OS, by passing --break-system-packages.
hint: See PEP 668 for the detailed specification.

هذه حماية تضعها توزيعات Debian 12 وUbuntu 23.04 وما بعدها (وبايثون Homebrew على ماك): بايثون النظام تعتمد عليه أدوات النظام نفسه، فلا يُسمح لـ pip بتغيير مكتباته. الرسالة نفسها تعطيك الحلول:

• مكتبة لمشروعك؟ بيئة افتراضية، كما في الوصفة فوق. هذا الحل في 99% من الحالات.
• أداة تشغّلها من الطرفية (مثل black أو httpie)؟ pipx install black. pipx ينشئ لكل أداة بيئة افتراضية خاصة بها ويضعها في PATH.
• مكتبة يحتاجها النظام نفسه؟ sudo apt install python3-requests.

تصحيح لنصيحة منتشرة: قد تقرأ أن pip install --user هو البديل الآمن. على هذه الأنظمة لا يعمل أيضًا؛ جرّبناه على Ubuntu 24.04 فأعطى نفس الخطأ. أما --break-system-packages فاسمه يصف ما يفعله بالضبط.

3) ensurepip is not available عند إنشاء البيئة

تتبع النصيحة وتكتب python3 -m venv .venv على Ubuntu، فيظهر:

The virtual environment was not created successfully because ensurepip is not
available.  On Debian/Ubuntu systems, you need to install the python3-venv
package using the following command.

    apt install python3.12-venv

You may need to use sudo with that command.  After installing the python3-venv
package, recreate your virtual environment.

Ubuntu وDebian يفصلان أداة البيئات الافتراضية في حزمة مستقلة. نفّذ الأمر المذكور بالضبط (رقم الإصدار فيه يطابق بايثون عندك)، ثم احذف المجلد الناقص وأعد إنشاءه:

sudo apt install python3.12-venv
rm -rf .venv
python3 -m venv .venv

4) Could not find a version that satisfies the requirement

هذه الرسالة لها سببان مختلفان تمامًا، والسطر قبلها هو ما يفرّق بينهما.

السبب الأول: الاسم غير موجود.

ERROR: Could not find a version that satisfies the requirement thispackagedoesnotexist-tcf (from versions: none)
ERROR: No matching distribution found for thispackagedoesnotexist-tcf

(from versions: none) تعني أن PyPI لا يعرف هذا الاسم أصلًا. تحقق من الإملاء في pypi.org. وانتبه: اسم الحزمة في pip قد يختلف عن اسم الاستيراد في الكود. تكتب import cv2 لكن تثبّت opencv-python، وتكتب import sklearn لكن تثبّت scikit-learn، وتكتب from PIL import Image لكن تثبّت pillow.

احذر الأسماء المشابهة: حزم بأسماء قريبة من المكتبات الشهيرة (حرف ناقص أو زائد) نُشرت على PyPI في حوادث موثّقة لتسرق بيانات من يثبّتها بالخطأ. انسخ اسم الحزمة من صفحتها الرسمية بدل كتابته من الذاكرة.

السبب الثاني: الإصدار لا يدعم بايثون الذي عندك. طلبنا Django 6.0 في بيئة Python 3.11:

ERROR: Ignored the following versions that require a different python version:
6.0 Requires-Python >=3.12; 6.0.1 Requires-Python >=3.12; ...
ERROR: Could not find a version that satisfies the requirement django==6.0
(from versions: 1.1.3, 1.1.4, ... 5.2.18)
ERROR: No matching distribution found for django==6.0

السطر الأول يقول كل شيء: الإصدار موجود، لكنه يتطلب Python 3.12 أو أحدث. الحل إما ترقية بايثون وإنشاء البيئة من جديد بالنسخة الأحدث، أو طلب إصدار يدعم نسختك (هنا django<6). تحقق بـ python --version داخل البيئة المفعّلة.

5) فشل البناء أثناء التثبيت

Collecting numpy==1.21.0
  Using cached numpy-1.21.0.zip (10.3 MB)
  Installing build dependencies: started
  Installing build dependencies: finished with status 'done'
  Getting requirements to build wheel: started
  ...
ERROR: ...

انظر إلى السطر الثاني: pip نزّل ملف .zip، أي الكود المصدري، لا ملف .whl جاهزًا، ثم بدأ يبني. هذه هي العلامة التي تبحث عنها. وتتنوّع رسالة الفشل بعدها (Microsoft Visual C++ 14.0 or greater is required على ويندوز، أو أخطاء gcc على لينكس، أو Failed to build)، لكن السبب الشائع واحد: لا توجد حزمة جاهزة (wheel) لهذا الإصدار على نسخة بايثون عندك، فيحاول pip ترجمة المكتبة من الكود المصدري. هذا ما حدث حين طلبنا numpy==1.21.0 على Python 3.13: إصدار من 2021 لم تُبنَ له حزم لبايثون صدر بعده بسنوات، فانتهى البناء بخطأ.

قبل تثبيت أدوات ترجمة ضخمة:

1. هل حدّدت إصدارًا قديمًا؟ غالبًا في requirements.txt من مشروع قديم. جرّب الإصدار الأحدث، فالمكتبات الشهيرة توفّر wheels للإصدارات الحديثة من بايثون.
2. حدّث pip: python -m pip install --upgrade pip. نسخ pip القديمة قد لا تتعرّف على صيغ wheels الأحدث، فتلجأ للبناء بلا داعٍ.
3. بايثون صدر للتو؟ المكتبات تحتاج وقتًا لتوفير wheels لكل إصدار جديد من بايثون. استخدم الإصدار السابق مؤقتًا.

6) التثبيت نجح، ومع ذلك ModuleNotFoundError

Successfully installed requests-2.34.2

ثم:

ModuleNotFoundError: No module named 'requests'

هذه أكثر حالة مربكة، وهي تؤكد القاعدة الأولى: pip ثبّت في بايثون، وكودك يعمل ببايثون آخر. قارن من نفس الطرفية:

python -m pip --version
python -c "import sys; print(sys.executable)"

إن لم يشيرا إلى نفس المجلد فقد وجدت المشكلة. وإن كنت تشغّل الكود من VS Code أو PyCharm، فتأكد أن المحرّر يستخدم مفسّر .venv (في VS Code: Python: Select Interpreter من لوحة الأوامر). التفاصيل في حل ModuleNotFoundError.

7) Permission denied

ERROR: Could not install packages due to an OSError: [Errno 13] Permission denied

pip يحاول الكتابة في مجلد لا تملك صلاحية عليه، غالبًا مكتبات بايثون مثبّت للنظام كله. sudo pip install يُخفي الرسالة لكنه يكتب فوق مكتبات النظام. البيئة الافتراضية تُنشأ داخل مجلد مشروعك، فلا تحتاج صلاحيات أصلًا. ولصلاحيات لينكس عمومًا راجع حل Permission denied في لينكس.

قائمة تحقّق

1. بيئة افتراضية لكل مشروع: python3 -m venv .venv ثم التفعيل.
2. ثبّت دائمًا بـ python -m pip install، لا بـ pip وحدها.
3. externally-managed-environment؟ بيئة افتراضية، أو pipx للأدوات. لا sudo ولا --user ولا --break-system-packages.
4. ensurepip is not available؟ sudo apt install python3.X-venv ثم احذف .venv وأعد إنشاءها.
5. Could not find a version؟ اقرأ السطر قبله: versions: none تعني الاسم خطأ، وRequires-Python تعني إصدار بايثون لا يناسب.
6. فشل البناء؟ إصدار المكتبة قديم على بايثون حديث غالبًا: اطلب الأحدث وحدّث pip.
7. نجح التثبيت ولم تجد المكتبة؟ قارن python -m pip --version مع sys.executable.

أكمل الأساس في مسار بايثون بالعربي، ولأخطاء الكود نفسه بعد التثبيت راجع أخطاء بايثون الشائعة. والمشكلة نفسها بنكهة JavaScript في حل أخطاء npm install.