Installation de cuPyNumeric (utilisateur)

Objectif

Utilisez cette compétence pour installer cuPyNumeric en vue de l'utiliser depuis Python et vérifier que l'installation fonctionne correctement (y compris l'utilisation du GPU). Appliquez-la chaque fois qu'un utilisateur souhaite exécuter cuPyNumeric via conda ou pip. Ne l'utilisez pas pour compiler à partir des sources (pour modifier ou contribuer) — ce n'est pas du ressort de cette compétence.

Règles obligatoires

Ne jamais exécuter d'installations. Ne lancez pas pip install, conda install ou tout autre installeur. Affichez la commande ; laissez l'utilisateur l'exécuter.
Toujours isoler. Pas d'installation dans le conda de base, le Python système ou des environnements globaux partagés.
Détecter avant de recommander. Les vérifications en lecture seule avec --version sont acceptables.

Prérequis

Confirmez ces conditions système avant de recommander une installation :

GPU : Compute Capability ≥ 7.0 (Volta+). CPU uniquement est également supporté.
CUDA : 12.2+.
OS : Linux (x86_64 / aarch64), macOS aarch64 (wheels pip uniquement), Windows via WSL.
Python : 3.11 à 3.14 sur Linux ; 3.11 à 3.13 sur macOS aarch64.
conda : ≥ 24.1 (chemin conda uniquement).
Gestionnaire de paquets : conda (recommandé en amont) ou pip. Si aucun n'est présent, initialisez-en un d'abord (voir Instructions).

Instructions

Suivez ces étapes dans l'ordre : confirmez les prérequis, posez les questions de périmètre, installez via le chemin choisi, puis vérifiez.

Demander avant d'installer

Gestionnaire de paquets ? Vérifiez conda --version et pip --version. Préférez conda (recommandé en amont) ; basculez sur pip en secours.
Cible d'environnement ? Machine GPU, ordinateur portable CPU uniquement, cloud, conteneur ou serveur/distant.
Version de CUDA ? Demandez uniquement si vous forcez la variante GPU sur un hôte sans GPU visible. Vérifiez avec nvidia-smi / nvcc --version.

Amorce — installer un gestionnaire de paquets en premier

Si ni conda ni pip n'est disponible, installez-en un. Fournissez la commande et le lien de documentation ; ne l'exécutez pas — curl | bash nécessite la confiance de l'utilisateur.

Recommandé : Miniforge (conda complet, conda-forge par défaut)

curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh"
bash "Miniforge3-$(uname)-$(uname -m).sh"

Documentation : https://github.com/conda-forge/miniforge

Alternative : Python + pip

Installez Python depuis le gestionnaire de paquets de votre OS (apt/dnf/brew) ou https://www.python.org/downloads/. Si pip manque sur un Python existant : python -m ensurepip --upgrade.

Après l'installation, ouvrez un nouveau shell pour que le binaire soit dans le PATH.

Installer — chemin conda

conda create -n cupynumeric -c conda-forge -c legate cupynumeric
conda activate cupynumeric

Dans un environnement existant : conda install -c conda-forge -c legate cupynumeric.

conda sélectionne automatiquement la variante GPU ou CPU selon que nvidia-smi fonctionne au moment de l'installation. Pour remplacer cela, voir ci-dessous.

Forcer la variante GPU

Définissez CONDA_OVERRIDE_CUDA uniquement quand aucun GPU n'est visible au moment de l'installation (par exemple en construisant un conteneur pour un hôte GPU). Utilisez la version CUDA de l'hôte d'exécution :

CONDA_OVERRIDE_CUDA="12.2" conda install -c conda-forge -c legate cupynumeric

Nightly (moins validé)

conda install -c conda-forge -c legate-nightly cupynumeric

Installer — chemin pip

python -m venv .venv
source .venv/bin/activate
pip install nvidia-cupynumeric

Vérifier

Test de santé (toujours exécuter)

Exécutez un script autonome via le lanceur legate — pas besoin de cloner le repo.

TMP=$(mktemp -d)
cat > "$TMP/smoke.py" <<'EOF'
import cupynumeric as np
a = np.arange(10)
b = np.ones((4, 4))
print("sum:", a.sum())            # expect 45
print("matmul:", (b @ b).sum())   # expect 64.0
EOF
legate "$TMP/smoke.py"
rm -rf "$TMP"

Attendez-vous à sum: 45 et matmul: 64.0. Si legate est manquant, l'environnement n'est pas activé — voir Dépannage.

Vérification de l'utilisation du GPU (obligatoire si un GPU supporté est présent)

Un test de santé réussi ne prouve pas l'utilisation du GPU — une installation de variante CPU sur une machine GPU produit aussi des résultats corrects. Exécutez les deux étapes.

1. Forcer un lancement GPU. legate --gpus N demande N GPU ; échoue rapidement si aucun GPU n'est visible ou si la variante CPU est installée.

TMP=$(mktemp -d)
cat > "$TMP/check.py" <<'EOF'
import cupynumeric as np
print(np.ones((4096, 4096)).sum())
EOF
legate --gpus 1 "$TMP/check.py"
rm -rf "$TMP"

Attendez-vous à 16777216.0. Si vous voyez CUDA driver, libcudart ou no GPUs available, la variante CPU est installée ; réinstallez avec CONDA_OVERRIDE_CUDA.

2. Confirmez que le GPU a été utilisé. Exécutez une boucle matmul limitée en temps aux côtés de nvidia-smi, tout depuis un shell — pas de race à deux terminaux :

TMPDIR_GPU=$(mktemp -d)
SCRIPT="$TMPDIR_GPU/cupynumeric_gpu_check.py"
cat > "$SCRIPT" <<'EOF'
import cupynumeric as np, time
a = np.ones((10000, 10000))
deadline = time.time() + 20
iters = 0
while time.time() < deadline:
    b = a @ a
    _ = float(b.sum())   # force sync so the matmul actually runs
    iters += 1
print("iters:", iters)
EOF
legate --gpus 1 "$SCRIPT" &
WORKLOAD=$!
sleep 5                                     # buffer for Legate startup
for _ in $(seq 10); do                      # 10 samples at 1s — covers slow startup
  nvidia-smi --query-gpu=utilization.gpu,memory.used --format=csv,noheader
  sleep 1
done
wait "$WORKLOAD"
rm -rf "$TMPDIR_GPU"

Attendez-vous à memory.used dans la plage des Gio sur la plupart des échantillons et une utilisation GPU non triviale sur plusieurs. Si les deux restent à la ligne de base sur tous les échantillons, la variante GPU n'est pas installée — vérifiez conda list cupynumeric pour *_gpu (pas *_cpu).

Recettes plus approfondies

Voir verification_examples.md pour les vérifications multi-GPU, le fallback CPU, les conteneurs et le dépannage.

Limitations

Ne mélangez pas conda et pip dans un seul environnement. Le mélange annule la première installation et casse à l'import. Pour basculer, exécutez d'abord pip uninstall nvidia-cupynumeric ou conda remove cupynumeric.
Utilisez le lanceur legate pour les exécutions multi-GPU / multi-rank. Un python simple exécute un seul processus : legate --gpus 2 script.py.
Forcez la variante GPU sur un hôte CPU uniquement avec CONDA_OVERRIDE_CUDA. conda sélectionne sinon automatiquement la variante CPU ou GPU selon nvidia-smi au moment de l'installation.
Exigez Volta ou plus récent. Pascal (GTX 10xx / P100) n'est pas supporté.
Vérifiez conda --version ≥ 24.1. Les versions anciennes cassent silencieusement la sélection de variante.
Traitez multi-nœud / MPI / UCX comme hors du périmètre. Renvoyez à https://docs.nvidia.com/legate/latest/networking-wheels.html et https://docs.nvidia.com/legate/latest/mpi-wrapper.html.

Dépannage

ModuleNotFoundError: No module named 'cupynumeric' → Exécutez which python et pip list | grep cupynumeric (ou conda list | grep cupynumeric) depuis le même shell pour trouver l'inadéquation d'environnement.
ImportError mentionnant CUDA / libcudart → Réinstallez avec CONDA_OVERRIDE_CUDA="<votre-version-cuda>"; la variante CPU est sur une machine GPU ou les versions CUDA ne correspondent pas.
legate: command not found → Activez l'environnement, puis exécutez which legate pour confirmer.
Plus lent que NumPy sur un ordinateur portable → Attendez-vous à cela pour les petits problèmes (surcharge par tâche de Legate). Voir la FAQ de cuPyNumeric.

Voir aussi

references/verification_examples.md — recettes de vérification + dépannage.
Documentation en amont : https://docs.nvidia.com/cupynumeric/latest/installation.html
Exigences de Legate : https://docs.nvidia.com/legate/latest/installation.html

cupynumeric-install