
الدليل الكامل لإصلاح مشكلات تثبيت CUDA
, 12 دقيقة قراءة, By Jaber Jaber
Researchإذا كنت تبدأ مع تطوير CUDA، فالأرجح أنك صادفت مشكلات تثبيت محبطة. حللت مئات تجارب المطورين وجمعت هذا الدليل الشامل لمساعدتك على تجاوز أكثر مشكلات تثبيت CUDA شيوعا.
مرّ كل مطور CUDA بهذا: تثبت الأداة، وكل شيء يبدو سليما، ثم يعيد nvcc --version رسالة "command not found". أو أسوأ: كل شيء يعمل على جهازك ويتعطل على GPU شخص آخر. بعد مساعدة عشرات الفرق في تصحيح هذه المشكلات، رأيت المشكلات نفسها مرارا وتكرارا.
يغطي هذا الدليل كل مشكلة تثبيت CUDA رئيسية وكيفية إصلاحها بالضبط. لا مزيد من المحاولة والخطأ.
محتويات المقال
مشكلات شائعة:
مشكلات PATH ومتغيرات البيئة
عدم توافق إصدارات المشغل و مجموعة الأدوات
مشكلات خاصة ب WSL2
مشكلات Secure Boot و UEFI
اعتماديات حزم مكسورة
تثبيت cuDNN والتوافق
PyTorch لا يرى CUDA
مشكلات خاصة ب Windows
تثبيتات ناقصة
أفضل الممارسات للوقاية
1. مشكلات PATH ومتغيرات البيئة
المشكلة: يعيد nvcc --version رسالة "command not found"
هذه أكثر مشكلة يواجهها المطورون بعد تثبيت CUDA. الأداة مثبتة، لكن النظام لا يجد مصرف CUDA.
السبب الجذري: ملفات CUDA التنفيذية ليست في متغير بيئة PATH عند نظامك.
┌──────────────────────────────────────────────────────────────┐ │ Diagnosis Flow │ ├──────────────────────────────────────────────────────────────┤ │ │ │ $ nvcc --version │ │ → "command not found" │ │ │ │ $ which nvcc │ │ → (empty) │ │ │ │ $ ls /usr/local/cuda/bin/nvcc │ │ → File exists! ✓ │ │ │ │ Conclusion: CUDA is installed, PATH is wrong │ │ │ └──────────────────────────────────────────────────────────────┘
الحل لنظام Linux/Ubuntu:
الحل لنظام Windows:
افتح System Properties ثم Advanced ثم Environment Variables
أضف إلى PATH:
C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v11.8\binأنشئ متغيرا جديدا
CUDA_PATH:C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v11.8أعد تشغيل الطرفية أو بيئة التطوير
التحقق:
2. عدم توافق إصدارات المشغل و مجموعة الأدوات
المشكلة: "CUDA driver version is insufficient" أو أخطاء عدم توافق الإصدارات
السبب الجذري: مشغل NVIDIA عندك لا يدعم إصدار أدوات CUDA الذي ثبّته، أو يوجد عدم توافق بين مكونات CUDA مختلفة.
فهم إصدارات CUDA:
يعرض
nvidia-smiإصدار CUDA الأقصى الذي يدعمه مشغلكويعرض
nvcc --versionإصدار مجموعة الأدوات المثبت عندكقد يختلفان، وهذا سليم عادة (المشغل يدعم المجموعات الأقدم)
┌──────────────────────────────────────────────────────────────┐ │ CUDA Compatibility Matrix │ ├──────────────────────────────────────────────────────────────┤ │ │ │ CUDA Toolkit → Minimum Driver Version │ │ ──────────────────────────────────────────────── │ │ CUDA 12.x ≥ 525.60.13 (Linux) │ │ ≥ 527.41 (Windows) │ │ │ │ CUDA 11.x ≥ 450.80.02 (Linux) │ │ ≥ 452.39 (Windows) │ │ │ │ CUDA 10.x ≥ 410.48 (Linux) │ │ ≥ 411.31 (Windows) │ │ │ │ Rule: Driver version ≥ Toolkit requirement │ │ │ └──────────────────────────────────────────────────────────────┘
الحل 1: ترقية مشغلك
الحل 2: تثبيت إصدار CUDA متوافق
إن لم تستطع ترقية مشغلك، فثبّت مجموعة أدوات CUDA أقدم تطابق إصدار مشغلك. طالع مصفوفة توافق CUDA.
الحل 3: إصلاح عدم توافق NVML بين المشغل و المكتبة
يظهر هذا الخطأ كثيرا بعد تحديثات المشغل:
3. مشكلات خاصة ب WSL2
المشكلة: CUDA لا يعمل في WSL2 على Windows
ل WSL2 متطلبات فريدة لدعم CUDA تختلف عن تثبيتات Linux الأصلية.
┌──────────────────────────────────────────────────────────────┐ │ WSL2 CUDA Architecture (Critical Rules) │ ├──────────────────────────────────────────────────────────────┤ │ │ │ Windows Host │ │ ┌────────────────────────────────────────────────────────┐ │ │ │ NVIDIA Driver (WSL-enabled) ← Install HERE │ │ │ │ ├─ Manages GPU hardware │ │ │ │ └─ Exposes /dev/dxg to WSL2 │ │ │ └────────────────────────────────────────────────────────┘ │ │ │ │ │ ↓ (passthrough) │ │ ┌────────────────────────────────────────────────────────┐ │ │ │ WSL2 Ubuntu │ │ │ │ ├─ CUDA Toolkit ONLY ← Install HERE │ │ │ │ ├─ NO driver installation! │ │ │ │ └─ Uses Windows driver via /dev/dxg │ │ │ └────────────────────────────────────────────────────────┘ │ │ │ │ Common mistake: Installing NVIDIA driver in WSL2 │ │ Result: Conflicts and failures │ │ │ └──────────────────────────────────────────────────────────────┘
قواعد حاسمة ل WSL2:
لا تثبّت مشغلات NVIDIA داخل WSL2: فهي تأتي من Windows
ثبّت مجموعة أدوات CUDA فقط في WSL2، لا المشغل
يجب أن يحمل Windows مشغل NVIDIA المتوافق مع WSL2
الحل:
الخطوة 1: ثبّت مشغل Windows الصحيح نزّل المشغل المفعل ل CUDA لأجل WSL من صفحة WSL لدى NVIDIA.
الخطوة 2: تحقق من أن WSL2 يرى GPU
إن نجح هذا، فمشغل Windows مضبوط بشكل صحيح.
الخطوة 3: ثبّت مجموعة أدوات CUDA في WSL2
الخطوة 4: اضبط متغيرات البيئة
مشكلات WSL2 الشائعة:
المشكلة: "GPU not detected in WSL2"
تأكد من أن Windows يحمل المشغل المفعل ل WSL2
تحقق من إصدار نواة WSL:
wsl cat /proc/version(يلزم ≥ 5.10.43.3)حدّث WSL:
wsl --updateفي PowerShell
المشكلة: إصدارات CUDA غير متوافقة
استخدم CUDA 11.0 أو أحدث فقط في WSL2
لا تخلط تثبيتات CUDA من طرق مختلفة
4. مشكلات Secure Boot و UEFI
المشكلة: "Required key not available" أو مشغلات لا تحمل مع Secure Boot
السبب الجذري: يمنع Secure Boot في UEFI تحميل وحدات نواة غير موقعة، ومشغلات NVIDIA منها.
الحل 1: عطّل Secure Boot (الأسهل)
أعد التشغيل وادخل إلى BIOS/UEFI (عادة DEL أو F2 أو F12 أثناء الإقلاع)
انتقل إلى إعدادات Security أو Boot
عطّل Secure Boot
احفظ واخرج
أعد الإقلاع إلى Linux
**الحل 2: وقّع وحدات NVIDIA (مع إبقاء Secure Boot مفعل)
**الحل 3: استخدم توقيع DKMS المدمج (Ubuntu 18.04 فصاعد)
التحقق:
5. اعتماديات حزم مكسورة
المشكلة: "Unable to correct problems, you have held broken packages" أو إخفاقات apt-get
يحدث هذا عادة عندما تتعارض تثبيتات CUDA مع حزم قائمة أو تثبيتات سابقة ناقصة.
التشخيص:
الحل 1: منهج الصفحة النظيفة
الحل 2: إصلاح تعارضات اعتماديات محددة
الحل 3: معالجة تعارضات "الملف موجود أصلا"
للمشكلات المستعصية:
6. تثبيت cuDNN والتوافق
المشكلة: عدم توافق إصدار cuDNN أو "cannot find cuDNN"
السبب الجذري: تتطلب أطر التعلم العميق إصدارات cuDNN محددة يجب أن تطابق إصدار CUDA عندك.
┌──────────────────────────────────────────────────────────────┐ │ CUDA ↔ cuDNN Compatibility Matrix │ ├──────────────────────────────────────────────────────────────┤ │ │ │ CUDA Version → Compatible cuDNN Versions │ │ ──────────────────────────────────────────────────────── │ │ CUDA 12.4 cuDNN 9.x │ │ CUDA 12.1 cuDNN 8.9+ │ │ CUDA 11.8 cuDNN 8.6 to 8.9 │ │ CUDA 11.x cuDNN 8.x │ │ │ │ Framework requirements: │ │ • PyTorch 2.0+: cuDNN 8.5+ │ │ • TensorFlow 2.13+: cuDNN 8.6+ │ │ │ └──────────────────────────────────────────────────────────────┘
الحل 1: تثبيت cuDNN متوافق عبر apt (Ubuntu)
الحل 2: التثبيت اليدوي
نزّل cuDNN من صفحة cuDNN لدى NVIDIA (يتطلب حسابا مجانيا)
اختر الإصدار المطابق لمجموعة أدوات CUDA عندك
استخرج الملفات وانسخها:
التحقق:
الحل 3: إصدارات cuDNN متعددة مع Conda
خطأ شائع: "Loaded runtime CuDNN library X but source was compiled with Y"
معناه أن حزمة Python عندك تتوقع إصدار cuDNN مختلفا.
الإصلاح:
7. PyTorch لا يرى CUDA
المشكلة: يعيد torch.cuda.is_available() القيمة False
هذه من أكثر المشكلات إحباطا لمطوري التعلم العميق.
خطوات التشخيص:
┌──────────────────────────────────────────────────────────────┐ │ PyTorch CUDA Troubleshooting Decision Tree │ ├──────────────────────────────────────────────────────────────┤ │ │ │ torch.cuda.is_available() == False │ │ │ │ │ ├─→ pip list | grep torch shows "+cpu"? │ │ │ └─→ YES: Installed CPU-only version │ │ │ FIX: Reinstall with CUDA support │ │ │ │ │ ├─→ nvidia-smi fails? │ │ │ └─→ YES: Driver problem │ │ │ FIX: Install/update NVIDIA driver │ │ │ │ │ ├─→ torch.version.cuda > nvidia-smi CUDA? │ │ │ └─→ YES: Driver doesn't support PyTorch CUDA │ │ │ FIX: Upgrade driver or use older PyTorch │ │ │ │ │ └─→ CUDA_VISIBLE_DEVICES set incorrectly? │ │ └─→ YES: GPU hidden from PyTorch │ │ FIX: Unset or correct the variable │ │ │ └──────────────────────────────────────────────────────────────┘
أسباب شائعة وحلولها:
السبب 1: تثبيت PyTorch للمعالج فقط
هذه أكثر الحالات شيوعا. الأمر الافتراضي pip install torch يثبت إصدار المعالج فقط.
الحل:
السبب 2: إصدار CUDA في PyTorch لا يطابق المشغل
يحزم PyTNN وقت تشغيل CUDA الخاص به، لكن مشغلك يجب أن يدعمه.
الحل:
السبب 3: قدرة حساب خاطئة
قد لا تدعم بنى PyTorch الحديثة GPUs الأقدم.
تحقق من قدرة حساب GPU:
الحل:
قدرة حساب أقل من 3.5: غير مدعومة من PyTorch الحديث
قدرة حساب من 3.5 إلى 5.2: قد تلزم إصدارات PyTorch أقدم
قدرة حساب 5.0 فأكثر: مدعومة كليا
إن كان GPU عندك عتيقا جدا، ففكر في:
السبب 4: مشكلات البيئة و Conda
الحل:
السبب 5: __CODE_0__ مضبوط بشكل خاطئ
سكربت تشخيص سريع:
8. مشكلات خاصة ب Windows
المشكلة: "Cannot find compiler 'cl.exe' in PATH"
السبب الجذري: يتطلب CUDA على Windows مصرف C++ من Microsoft Visual Studio هو cl.exe، وهو غير مشمول في مجموعة أدوات CUDA.
┌──────────────────────────────────────────────────────────────┐ │ Windows CUDA Build Requirements │ ├──────────────────────────────────────────────────────────────┤ │ │ │ CUDA Toolkit alone is NOT enough on Windows! │ │ │ │ Required components: │ │ ┌────────────────────────────────────────────────────────┐ │ │ │ 1. CUDA Toolkit (nvcc, libraries) │ │ │ │ 2. Visual Studio with C++ tools (cl.exe) │ │ │ │ 3. Windows SDK │ │ │ └────────────────────────────────────────────────────────┘ │ │ │ │ CUDA and VS Compatibility: │ │ • CUDA 12.5+: VS 2019 16.11 to VS 2022 17.10 │ │ • CUDA 12.0-12.4: VS 2019 16.11 to VS 2022 17.7 │ │ • CUDA 11.8: VS 2019 16.11 to VS 2022 17.0 │ │ │ └──────────────────────────────────────────────────────────────┘
الحل:
الخطوة 1: ثبّت Visual Studio
نزّل Visual Studio Community (مجاني)
أثناء التثبيت، اختر "Desktop development with C++"
تأكد من تحديد هذه المكونات:
أدوات بناء MSVC v143 ل C++ (أو الأحدث)
Windows SDK
أدوات CMake ل C++
الخطوة 2: تحقق من التثبيت
الخطوة 3: أضف إلى PATH (إن لزم)
إن لم يعثر على cl.exe في Command Prompt العادي:
اعثر على موقع cl.exe (عادة):
أضفه إلى PATH النظام أو استخدم Developer Command Prompt الخاص ب Visual Studio
الخطوة 4: تحقق من أن CUDA يجد المصرف
مشكلات توافق إصدارات VS الشائعة:
إذا كان لديك VS 2022 17.10 أو أحدث مع CUDA 12.4 أو أقدم:
المشكلة: تعارضات GeForce Experience (Windows)
الحل:
عند تثبيت CUDA على Windows، استخدم Custom Installation وألغ تحديد:
GeForce Experience (إن كان مثبتا أصلا)
Display Driver (إن كان لديك مشغل يعمل أصلا)
ثبّت فقط:
CUDA Toolkit
أدوات التطوير
الوثائق
9. تثبيتات ناقصة
المشكلة: تحذيرات "Incomplete installation" أو "Driver not selected"
الأعراض:
يكتمل التثبيت لكن مع تحذيرات
nvidia-smiيعمل لكنnvccلاتفشل بعض أمثلة CUDA في التجميع
الحل 1: تثبيت الأدوات فقط (حين يعمل المشغل أصلا)
الحل 2: إعادة تثبيت كاملة
الحل 3: إصلاح المكونات الناقصة
إن كانت مكونات محددة فقط هي الناقصة:
10. أفضل الممارسات
الوقاية خير من العلاج
┌──────────────────────────────────────────────────────────────┐ │ The Right Way to Install CUDA │ ├──────────────────────────────────────────────────────────────┤ │ │ │ Step 1: Plan │ │ • Check GPU compute capability │ │ • Verify OS and kernel version │ │ • Research framework requirements │ │ • Pick compatible versions │ │ │ │ Step 2: Clean │ │ • Remove old installations completely │ │ • Clean package manager cache │ │ • Reboot if needed │ │ │ │ Step 3: Install (in order) │ │ 1. NVIDIA Driver │ │ 2. CUDA Toolkit │ │ 3. cuDNN │ │ 4. Framework (PyTorch/TensorFlow) │ │ │ │ Step 4: Verify │ │ • Test nvidia-smi │ │ • Test nvcc --version │ │ • Compile and run deviceQuery │ │ • Test framework GPU access │ │ │ │ Step 5: Document │ │ • Save your working environment │ │ • Record all version numbers │ │ • Keep notes for future reference │ │ │ └──────────────────────────────────────────────────────────────┘
قبل التثبيت:
تحقق من التوافق
قدرة حساب GPU
إصدار نظام التشغيل والنواة
متطلبات المشغل
متطلبات الأطر (إصدارات PyTorch/TensorFlow)
نظف التثبيتات القائمة
استخدم مصادر رسمية
نزّل من nvidia.com، لا من مستودعات طرف ثالث
تحقق من المجاميع الاختبارية
اتبع دليل التثبيت الرسمي لنظام تشغيلك
أثناء التثبيت:
ثبّت بالترتيب الصحيح
المشغل أولا (أو دع مثبت CUDA يتولاه)
مجموعة أدوات CUDA ثانيا
cuDNN ثالثا
الإطار (PyTorch/TensorFlow) أخيرا
استخدم المثبتات المحلية للاستقرار
قد تفشل المثبتات الشبكية أو تجلب إصدارات خاطئة
ملفات run المحلية تمنحك تحكما أكبر
دوّن إصداراتك
بعد التثبيت:
تحقق من كل شيء
أنشئ نسخة احتياطية للبيئة
وثّق إعدادك احتفظ بسجل يضم:
طراز GPU
إصدار المشغل
إصدار CUDA
إصدار cuDNN
إصدارات الأطر
إصدار نظام التشغيل والنواة
مسارات التثبيت الموصى بها:
للمبتدئين:
للمستخدمين المتقدمين:
للتعلم العميق:
حين تسوء الأمور:
لا تثبّت في ذعر
تثبيت إصدارات متعددة لن يصلح المشكلات
نظف أولا ثم أعد التثبيت
اقرأ رسائل الخطأ بعناية
معظم الأخطاء تخبرك بالضبط ما الخطأ
ابحث في Google عن رسالة الخطأ المحددة
راجع السجلات
اطلب المساعدة بالطريقة الصحيحة عند النشر في المنتديات، أدرج:
نظام التشغيل وإصداره
طراز GPU
ناتج
nvidia-smiناتج
nvcc --versionرسائل الخطأ كاملة
ما جربته أصلا
قائمة تشخيص سريعة
استخدم هذه القائمة حين لا يعمل CUDA:
┌──────────────────────────────────────────────────────────────┐ │ CUDA Troubleshooting Checklist │ ├──────────────────────────────────────────────────────────────┤ │ │ │ □ nvidia-smi shows GPU? │ │ → If no: Driver issue │ │ │ │ □ nvcc --version works? │ │ → If no: PATH issue │ │ │ │ □ CUDA version compatible with driver? │ │ → Check compatibility matrix │ │ │ │ □ cuDNN installed and compatible? │ │ → Check version matching │ │ │ │ □ PyTorch/TensorFlow sees GPU? │ │ → Check framework installation │ │ │ │ □ Secure Boot disabled (or modules signed)? │ │ → Check boot settings │ │ │ │ □ All environment variables set? │ │ → Check PATH, LD_LIBRARY_PATH, CUDA_HOME │ │ │ │ □ On WSL2? │ │ → Follow WSL2-specific guide │ │ │ │ □ On Windows? │ │ → Visual Studio installed? │ │ │ │ □ Package dependencies clean? │ │ → Run apt --fix-broken install │ │ │ └──────────────────────────────────────────────────────────────┘
الخلاصة
قد يكون تثبيت CUDA متعرجا، لكن معظم المشكلات تقع في هذه الفئات الشائعة. المفتاح هو:
تحديد المشكلة المحددة من رسائل الخطأ
فهم السبب الجذري (عدم توافق إصدارات، اعتماديات ناقصة، ونحوها)
تطبيق الحل المستهدف بدلا من إعادة تثبيت كل شيء
التحقق من الإصلاح باختبار سليم
تذكر: تثبيت CUDA عامل يتطلب:
عتاد GPU متوافقا
مشغل NVIDIA سليما
مجموعة أدوات CUDA
متغيرات بيئة صحيحة
(للتعلم العميق) cuDNN متوافقا
(للتعلم العميق) إطارا مثبتا بدعم CUDA
إن بقيت عالقا بعد تجربة هذه الحلول، فمجتمع CUDA في منتديات NVIDIA للمطورين و Stack Overflow موردان ممتازان.
آخر تحديث: أكتوبر 2025