انتقل إلى المحتوى
في هذه الصفحة
العودة إلى المدونة
الدليل الكامل لإصلاح مشكلات تثبيت CUDA

الدليل الكامل لإصلاح مشكلات تثبيت 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:

Shell
# Add these lines to your ~/.bashrc file
export PATH=/usr/local/cuda/bin:$PATH
export LD_LIBRARY_PATH=/usr/local/cuda/lib64:$LD_LIBRARY_PATH

# For specific CUDA versions (e.g., CUDA 11.8):
export CUDA_HOME=/usr/local/cuda-11.8
export PATH=$CUDA_HOME/bin:$PATH
export LD_LIBRARY_PATH=$CUDA_HOME/lib64:$LD_LIBRARY_PATH

# Apply the changes
source ~/.bashrc

الحل لنظام Windows:

  1. افتح System Properties ثم Advanced ثم Environment Variables

  2. أضف إلى PATH: C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v11.8\bin

  3. أنشئ متغيرا جديدا CUDA_PATH: C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v11.8

  4. أعد تشغيل الطرفية أو بيئة التطوير

التحقق:

Shell
nvcc --version
which nvcc  # Linux/Mac only

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: ترقية مشغلك

Shell
# Ubuntu/Debian
sudo ubuntu-drivers devices  # Check available drivers
sudo ubuntu-drivers autoinstall  # Install recommended driver
# OR
sudo apt install nvidia-driver-535  # Install specific version

# Verify
nvidia-smi

الحل 2: تثبيت إصدار CUDA متوافق

إن لم تستطع ترقية مشغلك، فثبّت مجموعة أدوات CUDA أقدم تطابق إصدار مشغلك. طالع مصفوفة توافق CUDA.

الحل 3: إصلاح عدم توافق NVML بين المشغل و المكتبة

يظهر هذا الخطأ كثيرا بعد تحديثات المشغل:

Shell
# The simplest solution: reboot your system
sudo reboot

# If reboot doesn't work, reload the driver
sudo rmmod nvidia_uvm
sudo rmmod nvidia_drm
sudo rmmod nvidia_modeset
sudo rmmod nvidia
sudo modprobe nvidia

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:

  1. لا تثبّت مشغلات NVIDIA داخل WSL2: فهي تأتي من Windows

  2. ثبّت مجموعة أدوات CUDA فقط في WSL2، لا المشغل

  3. يجب أن يحمل Windows مشغل NVIDIA المتوافق مع WSL2

الحل:

الخطوة 1: ثبّت مشغل Windows الصحيح نزّل المشغل المفعل ل CUDA لأجل WSL من صفحة WSL لدى NVIDIA.

الخطوة 2: تحقق من أن WSL2 يرى GPU

Shell
# In WSL2 terminal
nvidia-smi

إن نجح هذا، فمشغل Windows مضبوط بشكل صحيح.

الخطوة 3: ثبّت مجموعة أدوات CUDA في WSL2

Shell
wget https://developer.download.nvidia.com/compute/cuda/repos/wsl-ubuntu/x86_64/cuda-keyring_1.0-1_all.deb
sudo dpkg -i cuda-keyring_1.0-1_all.deb
sudo apt-get update
sudo apt-get install cuda-toolkit-12-1  # No driver installation!

الخطوة 4: اضبط متغيرات البيئة

Shell
echo 'export PATH=/usr/local/cuda/bin:$PATH' >> ~/.bashrc
echo 'export LD_LIBRARY_PATH=/usr/local/cuda/lib64:$LD_LIBRARY_PATH' >> ~/.bashrc
source ~/.bashrc

مشكلات 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 (الأسهل)

  1. أعد التشغيل وادخل إلى BIOS/UEFI (عادة DEL أو F2 أو F12 أثناء الإقلاع)

  2. انتقل إلى إعدادات Security أو Boot

  3. عطّل Secure Boot

  4. احفظ واخرج

  5. أعد الإقلاع إلى Linux

**الحل 2: وقّع وحدات NVIDIA (مع إبقاء Secure Boot مفعل)

Shell
# Generate MOK (Machine Owner Key)
openssl req -new -x509 -newkey rsa:2048 -keyout MOK.priv -outform DER -out MOK.der -nodes -days 36500 -subj "/CN=Custom MOK/"

# Enroll the key
sudo mokutil --import MOK.der
# You'll be prompted to create a password

# Reboot: you'll see MOK Manager
# Select "Enroll MOK" → "Continue" → "Yes"
# Enter the password you created
# Reboot again

# Now sign the NVIDIA modules
sudo /usr/src/linux-headers-$(uname -r)/scripts/sign-file sha256 ./MOK.priv ./MOK.der $(modinfo -n nvidia)

**الحل 3: استخدم توقيع DKMS المدمج (Ubuntu 18.04 فصاعد)

Shell
# During NVIDIA driver installation, you'll be prompted to create a password
# After reboot, MOK Manager appears automatically
# Select "Enroll MOK" and enter your password

التحقق:

Shell
# Check if driver is loaded
lsmod | grep nvidia

# If loaded, secure boot is working with signed modules
mokutil --sb-state  # Should show "SecureBoot enabled"

5. اعتماديات حزم مكسورة

المشكلة: "Unable to correct problems, you have held broken packages" أو إخفاقات apt-get

يحدث هذا عادة عندما تتعارض تثبيتات CUDA مع حزم قائمة أو تثبيتات سابقة ناقصة.

التشخيص:

Shell
sudo apt-get install -f  # Attempt to fix
sudo dpkg --configure -a  # Configure unconfigured packages
apt-cache policy cuda  # Check available versions

الحل 1: منهج الصفحة النظيفة

Shell
# Remove all CUDA and NVIDIA packages
sudo apt-get remove --purge '^nvidia-.*'
sudo apt-get remove --purge '^cuda-.*'
sudo apt-get remove --purge '^libnvidia-.*'
sudo apt-get autoremove
sudo apt-get autoclean

# Remove CUDA repository configurations
sudo rm /etc/apt/sources.list.d/cuda*
sudo rm /etc/apt/sources.list.d/nvidia*

# Clean apt cache
sudo apt-get clean

# Update package lists
sudo apt-get update

# Now reinstall from scratch

الحل 2: إصلاح تعارضات اعتماديات محددة

Shell
# If apt tells you a specific package is problematic
sudo dpkg --purge --force-all package-name

# Use aptitude for better dependency resolution
sudo apt-get install aptitude
sudo aptitude install cuda

# Aptitude will offer solutions: accept the one that installs/updates packages

الحل 3: معالجة تعارضات "الملف موجود أصلا"

Shell
# If error says "trying to overwrite '/path/to/file'"
# Find which package owns the conflicting file
dpkg -S /path/to/file

# Remove that package first
sudo apt-get remove conflicting-package

# Then continue with installation

للمشكلات المستعصية:

Shell
# Use local installer instead of apt
wget https://developer.download.nvidia.com/compute/cuda/12.1.0/local_installers/cuda_12.1.0_530.30.02_linux.run
sudo sh cuda_12.1.0_530.30.02_linux.run --toolkit --samples --silent

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)

Shell
# Check your CUDA version
nvcc --version

# For CUDA 11.8
sudo apt-get install libcudnn8=8.9.7.*-1+cuda11.8
sudo apt-get install libcudnn8-dev=8.9.7.*-1+cuda11.8

# For CUDA 12.x
sudo apt-get install libcudnn9-cuda-12

الحل 2: التثبيت اليدوي

  1. نزّل cuDNN من صفحة cuDNN لدى NVIDIA (يتطلب حسابا مجانيا)

  2. اختر الإصدار المطابق لمجموعة أدوات CUDA عندك

  3. استخرج الملفات وانسخها:

Shell
tar -xvf cudnn-linux-x86_64-8.9.7.29_cuda12-archive.tar.xz
cd cudnn-linux-x86_64-8.9.7.29_cuda12-archive

# Copy files to CUDA installation
sudo cp include/cudnn*.h /usr/local/cuda/include
sudo cp lib/libcudnn* /usr/local/cuda/lib64
sudo chmod a+r /usr/local/cuda/include/cudnn*.h /usr/local/cuda/lib64/libcudnn*

التحقق:

Shell
# Check cuDNN version
cat /usr/include/cudnn_version.h | grep CUDNN_MAJOR -A 2

# Or
cat /usr/local/cuda/include/cudnn_version.h | grep CUDNN_MAJOR -A 2

الحل 3: إصدارات cuDNN متعددة مع Conda

Shell
# Create isolated environment
conda create -n myenv python=3.10
conda activate myenv

# Install specific CUDA and cuDNN
conda install -c conda-forge cudatoolkit=11.8 cudnn=8.9.2

خطأ شائع: "Loaded runtime CuDNN library X but source was compiled with Y"

معناه أن حزمة Python عندك تتوقع إصدار cuDNN مختلفا.

الإصلاح:

Shell
# Option 1: Reinstall the package with matching cuDNN
pip uninstall tensorflow-gpu  # or pytorch
pip install tensorflow-gpu==2.15.0  # Version compatible with your cuDNN

# Option 2: Install the expected cuDNN version
sudo apt-get install libcudnn8=X.X.X.*-1+cudaY.Y  # Match the expected version

7. PyTorch لا يرى CUDA

المشكلة: يعيد torch.cuda.is_available() القيمة False

هذه من أكثر المشكلات إحباطا لمطوري التعلم العميق.

خطوات التشخيص:

Python
import torch
print(torch.__version__)
print(torch.cuda.is_available())
print(torch.version.cuda)  # CUDA version PyTorch was built with

# Try to create a CUDA tensor (provides better error messages)
try:
    torch.zeros(1).cuda()
except Exception as e:
    print(f"Error: {e}")
┌──────────────────────────────────────────────────────────────┐
│  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 يثبت إصدار المعالج فقط.

الحل:

Shell
# Uninstall current PyTorch
pip uninstall torch torchvision torchaudio

# Install with CUDA support (check pytorch.org for your CUDA version)
# For CUDA 11.8:
pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

# For CUDA 12.1:
pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

السبب 2: إصدار CUDA في PyTorch لا يطابق المشغل

يحزم PyTNN وقت تشغيل CUDA الخاص به، لكن مشغلك يجب أن يدعمه.

الحل:

Shell
# Check driver version
nvidia-smi  # Look at "Driver Version" and "CUDA Version"

# Install PyTorch version compatible with your driver
# If driver supports CUDA 11.8, install PyTorch with CUDA 11.8
# If driver supports CUDA 12.1+, you can use any lower CUDA version

السبب 3: قدرة حساب خاطئة

قد لا تدعم بنى PyTorch الحديثة GPUs الأقدم.

تحقق من قدرة حساب GPU:

Shell
# Method 1
nvidia-smi --query-gpu=compute_cap --format=csv

# Method 2 (if you can import torch)
python -c "import torch; print(torch.cuda.get_device_capability())"

الحل:

  • قدرة حساب أقل من 3.5: غير مدعومة من PyTorch الحديث

  • قدرة حساب من 3.5 إلى 5.2: قد تلزم إصدارات PyTorch أقدم

  • قدرة حساب 5.0 فأكثر: مدعومة كليا

إن كان GPU عندك عتيقا جدا، ففكر في:

Shell
# Install older PyTorch version (e.g., 1.7.1 for older GPUs)
pip install torch==1.7.1+cu101 torchvision==0.8.2+cu101 -f https://download.pytorch.org/whl/torch_stable.html

السبب 4: مشكلات البيئة و Conda

الحل:

Shell
# Create fresh environment
conda create -n pytorch_env python=3.10
conda activate pytorch_env

# Install PyTorch through conda (often more reliable)
conda install pytorch torchvision torchaudio pytorch-cuda=11.8 -c pytorch -c nvidia

السبب 5: __CODE_0__ مضبوط بشكل خاطئ

Shell
# Check if the variable is hiding your GPU
echo $CUDA_VISIBLE_DEVICES

# If it's set to empty or wrong value, unset it
unset CUDA_VISIBLE_DEVICES

# Or set it correctly (0 for first GPU)
export CUDA_VISIBLE_DEVICES=0

سكربت تشخيص سريع:

Python
# Run this diagnostic script
import torch
print(f"PyTorch version: {torch.__version__}")
print(f"CUDA available: {torch.cuda.is_available()}")
print(f"CUDA version: {torch.version.cuda}")
print(f"Number of GPUs: {torch.cuda.device_count()}")
if torch.cuda.is_available():
    print(f"GPU Name: {torch.cuda.get_device_name(0)}")
    print(f"GPU Compute Capability: {torch.cuda.get_device_capability(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

  1. نزّل Visual Studio Community (مجاني)

  2. أثناء التثبيت، اختر "Desktop development with C++"

  3. تأكد من تحديد هذه المكونات:

    • أدوات بناء MSVC v143 ل C++ (أو الأحدث)

    • Windows SDK

    • أدوات CMake ل C++

الخطوة 2: تحقق من التثبيت

Command Prompt
# Open "Developer Command Prompt for VS"
where cl.exe
cl.exe

الخطوة 3: أضف إلى PATH (إن لزم)

إن لم يعثر على cl.exe في Command Prompt العادي:

  1. اعثر على موقع cl.exe (عادة):

Text
C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Tools\MSVC\14.XX.XXXXX\bin\Hostx64\x64
  1. أضفه إلى PATH النظام أو استخدم Developer Command Prompt الخاص ب Visual Studio

الخطوة 4: تحقق من أن CUDA يجد المصرف

Command Prompt
nvcc --version
nvcc test.cu  # Try compiling a simple CUDA file

مشكلات توافق إصدارات VS الشائعة:

إذا كان لديك VS 2022 17.10 أو أحدث مع CUDA 12.4 أو أقدم:

Command Prompt
# Option 1: Upgrade CUDA to 12.5+
# Option 2: Add this flag when compiling
nvcc -allow-unsupported-compiler your_file.cu

# Option 3: Downgrade VS to 17.9
# Option 4: Use flag in CMake
set CMAKE_CUDA_FLAGS=-allow-unsupported-compiler

المشكلة: تعارضات GeForce Experience (Windows)

الحل:

عند تثبيت CUDA على Windows، استخدم Custom Installation وألغ تحديد:

  • GeForce Experience (إن كان مثبتا أصلا)

  • Display Driver (إن كان لديك مشغل يعمل أصلا)

ثبّت فقط:

  • CUDA Toolkit

  • أدوات التطوير

  • الوثائق


9. تثبيتات ناقصة

المشكلة: تحذيرات "Incomplete installation" أو "Driver not selected"

الأعراض:

  • يكتمل التثبيت لكن مع تحذيرات

  • nvidia-smi يعمل لكن nvcc لا

  • تفشل بعض أمثلة CUDA في التجميع

الحل 1: تثبيت الأدوات فقط (حين يعمل المشغل أصلا)

Shell
# Use the runfile installer with toolkit-only flag
sudo sh cuda_12.1.0_530.30.02_linux.run --toolkit --samples --silent

# Set environment variables
export PATH=/usr/local/cuda-12.1/bin:$PATH
export LD_LIBRARY_PATH=/usr/local/cuda-12.1/lib64:$LD_LIBRARY_PATH

الحل 2: إعادة تثبيت كاملة

Shell
# Complete cleanup
sudo apt-get remove --purge '^nvidia-.*'
sudo apt-get remove --purge '^cuda-.*'
sudo apt-get autoremove

# Remove any manual installations
sudo rm -rf /usr/local/cuda*

# Reboot
sudo reboot

# Fresh installation using recommended method
sudo apt-get update
sudo apt-get install cuda-toolkit-12-1 nvidia-driver-535

الحل 3: إصلاح المكونات الناقصة

إن كانت مكونات محددة فقط هي الناقصة:

Shell
# Install missing samples
sudo apt-get install cuda-samples-12-1

# Install missing libraries
sudo apt-get install cuda-libraries-12-1

# Install development files
sudo apt-get install cuda-libraries-dev-12-1

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                           │
│                                                              │
└──────────────────────────────────────────────────────────────┘

قبل التثبيت:

  1. تحقق من التوافق

    • قدرة حساب GPU

    • إصدار نظام التشغيل والنواة

    • متطلبات المشغل

    • متطلبات الأطر (إصدارات PyTorch/TensorFlow)

  2. نظف التثبيتات القائمة

Shell
sudo apt-get remove --purge '^nvidia-.*' '^cuda-.*'
sudo apt-get autoremove
  1. استخدم مصادر رسمية

    • نزّل من nvidia.com، لا من مستودعات طرف ثالث

    • تحقق من المجاميع الاختبارية

    • اتبع دليل التثبيت الرسمي لنظام تشغيلك

أثناء التثبيت:

  1. ثبّت بالترتيب الصحيح

    • المشغل أولا (أو دع مثبت CUDA يتولاه)

    • مجموعة أدوات CUDA ثانيا

    • cuDNN ثالثا

    • الإطار (PyTorch/TensorFlow) أخيرا

  2. استخدم المثبتات المحلية للاستقرار

    • قد تفشل المثبتات الشبكية أو تجلب إصدارات خاطئة

    • ملفات run المحلية تمنحك تحكما أكبر

  3. دوّن إصداراتك

Shell
# Save this info for troubleshooting
nvidia-smi
nvcc --version
cat /usr/include/cudnn_version.h | grep CUDNN_MAJOR -A 2

بعد التثبيت:

  1. تحقق من كل شيء

Shell
# Driver
nvidia-smi

# Toolkit
nvcc --version

# Test compilation
cd /usr/local/cuda/samples/1_Utilities/deviceQuery
sudo make
./deviceQuery
  1. أنشئ نسخة احتياطية للبيئة

Shell
# Save your working environment
conda env export > working_cuda_env.yml

# Or with pip
pip freeze > requirements.txt
  1. وثّق إعدادك احتفظ بسجل يضم:

    • طراز GPU

    • إصدار المشغل

    • إصدار CUDA

    • إصدار cuDNN

    • إصدارات الأطر

    • إصدار نظام التشغيل والنواة

مسارات التثبيت الموصى بها:

للمبتدئين:

Shell
# Ubuntu: Use apt packages (easiest)
sudo apt-get update
sudo apt-get install nvidia-driver-535
sudo apt-get install cuda-toolkit-12-1

للمستخدمين المتقدمين:

Shell
# Use runfile for maximum control
wget https://developer.download.nvidia.com/compute/cuda/12.1.0/local_installers/cuda_12.1.0_530.30.02_linux.run
sudo sh cuda_12.1.0_530.30.02_linux.run

للتعلم العميق:

Shell
# Use Docker containers (most reliable)
docker pull nvidia/cuda:12.1.0-cudnn8-devel-ubuntu22.04

# Or use Conda for isolated environments
conda create -n ml_env python=3.10
conda activate ml_env
conda install pytorch torchvision pytorch-cuda=12.1 -c pytorch -c nvidia

حين تسوء الأمور:

  1. لا تثبّت في ذعر

    • تثبيت إصدارات متعددة لن يصلح المشكلات

    • نظف أولا ثم أعد التثبيت

  2. اقرأ رسائل الخطأ بعناية

    • معظم الأخطاء تخبرك بالضبط ما الخطأ

    • ابحث في Google عن رسالة الخطأ المحددة

  3. راجع السجلات

Shell
# CUDA installer logs
cat /var/log/cuda-installer.log

# System logs
dmesg | grep -i nvidia
journalctl -xe | grep -i nvidia
  1. اطلب المساعدة بالطريقة الصحيحة عند النشر في المنتديات، أدرج:

    • نظام التشغيل وإصداره

    • طراز 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 متعرجا، لكن معظم المشكلات تقع في هذه الفئات الشائعة. المفتاح هو:

  1. تحديد المشكلة المحددة من رسائل الخطأ

  2. فهم السبب الجذري (عدم توافق إصدارات، اعتماديات ناقصة، ونحوها)

  3. تطبيق الحل المستهدف بدلا من إعادة تثبيت كل شيء

  4. التحقق من الإصلاح باختبار سليم

تذكر: تثبيت CUDA عامل يتطلب:

  • عتاد GPU متوافقا

  • مشغل NVIDIA سليما

  • مجموعة أدوات CUDA

  • متغيرات بيئة صحيحة

  • (للتعلم العميق) cuDNN متوافقا

  • (للتعلم العميق) إطارا مثبتا بدعم CUDA

إن بقيت عالقا بعد تجربة هذه الحلول، فمجتمع CUDA في منتديات NVIDIA للمطورين و Stack Overflow موردان ممتازان.


آخر تحديث: أكتوبر 2025