Python : dépannage

Lire une trace d’erreur

Traceback (most recent call last):
  File "app.py", line 12, in <module>
    resultat = calculer(donnees)
  File "calcul.py", line 5, in calculer
    return total / compte
ZeroDivisionError: division by zero

Lire de bas en haut : la dernière ligne donne le type d’erreur et le message ; les lignes au-dessus donnent le chemin d’appel, la dernière ligne File étant l’endroit où l’erreur s’est produite.

Quel Python, quel environnement ?

which python python3 pip
python --version
python -c 'import sys; print(sys.executable); print(sys.prefix)'
python -c 'import sys; print("\n".join(sys.path))'
pip --version                      # indique l'interpréteur auquel pip est lié
python -m pip list

La plupart des problèmes de « module introuvable » viennent d’un mauvais interpréteur : utiliser python -m pip pour garantir que pip installe pour le Python qu’on exécute.

Erreurs fréquentes

Message	Cause et solution
`ModuleNotFoundError: No module named 'x'`	Paquet absent de l’environnement actif : `python -m pip install x`
`ImportError: cannot import name`	Version du paquet différente, ou import circulaire
`externally-managed-environment`	Utiliser un venv (Environnements virtuels)
`SyntaxError` sur du code récent	Version de Python trop ancienne pour la syntaxe : `python --version`
`IndentationError`	Tabulations et espaces mélangés
`UnicodeDecodeError` / `UnicodeEncodeError`	Préciser `encoding="utf-8"` ; `export PYTHONIOENCODING=utf-8` pour la sortie
`PermissionError`	Droits du fichier ou du dossier : `ls -l`, utilisateur du processus
`FileNotFoundError`	Chemin relatif : il dépend du dossier courant, utiliser `Path(__file__).parent`
`RecursionError`	Récursion infinie ou trop profonde
`KeyError`, `AttributeError`, `TypeError`	Donnée inattendue : afficher la valeur avec `print(repr(x))`
`ssl.SSLCertVerificationError`	`sudo apt install ca-certificates`
`pip` introuvable ou paquet qui ne compile pas	`sudo apt install python3-pip build-essential python3-dev`

Déboguer

import pdb

def calculer(a, b):
    pdb.set_trace()          # ou breakpoint()
    return a / b

python -m pdb script.py

Commande `pdb`	Rôle
`n`	Ligne suivante
`s`	Entrer dans la fonction
`c`	Continuer
`p variable`	Afficher une valeur
`l`	Afficher le code autour
`w`	Pile d’appels
`q`	Quitter

Pour l’analyse après plantage : python -i script.py, puis import pdb; pdb.pm().

Journalisation

import logging

logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s %(levelname)s %(name)s : %(message)s",
)
log = logging.getLogger(__name__)
log.info("démarrage")
log.exception("erreur")      # dans un bloc except : inclut la trace

Pour un service systemd, écrire sur la sortie standard : journald la collecte (journalctl -u monapp).

Lenteurs

python -X importtime script.py 2> imports.txt          # temps d'import
python -m cProfile -s cumtime script.py | head -20      # profil d'exécution
time python script.py

Pistes : boucles évitables (compréhensions, bibliothèques vectorisées), lectures de fichiers en bloc, requêtes SQL multiples, requêtes réseau sans cache.

Mémoire

python -c 'import resource; print(resource.getrusage(resource.RUSAGE_SELF).ru_maxrss, "Ko")'

Un processus tué sans message est probablement arrêté par le noyau faute de mémoire : sudo journalctl -k | grep -i "out of memory".

Après une montée de version d’Ubuntu

Symptôme	Action
Environnements virtuels cassés (`bad interpreter`)	Les recréer
Un paquet ne s’installe plus	Chercher une version compatible avec la nouvelle version de Python
Un module du système est introuvable	Ne pas réinstaller Python : `sudo apt install --reinstall python3` et vérifier `/usr/bin/python3`

Ubuntu 24.04 et 26.04 : différences à connaître

Les diagnostics sont identiques. Sous Python 3.14, certains avertissements de dépréciation deviennent des erreurs : lancer les tests avec python -W error::DeprecationWarning pour les repérer avant de migrer.

Pour aller plus loin

Bibliothèque standard
Retour : Installation