LEGB : la résolution des noms LEGB: name resolution

Lire un nom dans une fonction cherche dans quatre portées, dans un ordre fixe : Local, Enclosing, Global, Built-in. Mais Python décide si un nom est local avant même d'exécuter la moindre ligne — en scannant tout le corps de la fonction à la recherche d'une assignation. Le résultat : lire une variable avant de l'assigner, plus bas dans la même fonction, ne va pas chercher la variable globale du même nom. Ça lève une UnboundLocalError. Reading a name inside a function searches four scopes, in a fixed order: Local, Enclosing, Global, Built-in. But Python decides whether a name is local before running a single line — by scanning the whole function body for an assignment. The result: reading a variable before assigning it, further down in the same function, doesn't fall back to the global variable of the same name. It raises UnboundLocalError.

Audience
Dev qui a vu une UnboundLocalError sur une variable qui existe pourtant, plus haut, en global Dev who's hit UnboundLocalError on a variable that clearly exists, higher up, as a global
ChapitresChapters
5
LectureReading
≈ 18 min
NiveauLevel
●●○○
Date
Juil 2026 Jul 2026

PortéeLEGBScoping

SommaireContents ·
№ 01CadrageFraming3 min

Un nom lu n'est jamais résolu au hasard — il traverse quatre portées, dans un ordre fixe.A name read is never resolved at random — it walks four scopes, in a fixed order.

Le Vol. I a posé la question de la liaison : à quel objet un nom est-il lié. Ce volume la rouvre sous un angle différent — non plus quel objet, mais quand et où ce nom est cherché. Quand Python rencontre un nom à l'intérieur d'une fonction, il ne le cherche pas n'importe où : il consulte quatre portées, dans un ordre strict — Local (la fonction elle-même), Enclosing (les fonctions englobantes), Global (le module), Built-in (print, len, et le reste). Il s'arrête à la première portée où le nom existe, sans continuer plus loin.Vol. I raised the question of binding: which object a name is bound to. This volume reopens it from a different angle — not which object, but when and where that name is looked up. When Python encounters a name inside a function, it doesn't search just anywhere: it consults four scopes, in strict order — Local (the function itself), Enclosing (the enclosing functions), Global (the module), Built-in (print, len, and the rest). It stops at the first scope where the name exists, without looking further.

Les quatre portées, dans leur ordre de rechercheThe four scopes, in search order
x = "globale"                 # portée Global

def externe():
    x = "englobante"           # portée Enclosing (vue depuis interne)
    def interne():
        x = "locale"           # portée Local
        print(x)               # 'locale'   -> trouvé en L, s'arrête là
    interne()
externe()

def sans_local():
    x = "englobante"
    def interne():
        print(x)               # pas de x en L -> cherche en E -> 'englobante'
    interne()
sans_local()

print(len([1, 2]))              # len : ni L, ni E, ni G -> Built-in
Le sous-réflexe du numéroThis issue's sub-reflex

Face à un nom lu dans une fonction, demande : où, dans les quatre portées, ce nom existe-t-il en premier ? Pas « où pourrait-il exister » — la première portée qui le contient gagne, et les autres ne sont jamais consultées.Facing a name read inside a function, ask: in which of the four scopes does this name exist first? Not "where could it exist" — the first scope that holds it wins, and the others are never consulted.

L'ordre n'est pas négociableThe order isn't negotiable

L, puis E, puis G, puis B — jamais dans un autre sens, jamais en parallèle. Un nom local masque toujours un nom global du même nom ; un built-in redéfini en global (écraser list, par exemple) masque le built-in partout dans le module.L, then E, then G, then B — never the other way, never in parallel. A local name always shadows a global name of the same name; a built-in redefined as a global (shadowing list, for instance) hides the built-in everywhere in the module.

№ 02La surpriseThe surprise4 min

Une assignation plus bas dans la fonction rend un nom local — même avant de s'exécuter.An assignment further down the function makes a name local — even before it runs.

Voici la surprise que la plupart des devs découvrent par accident : Python ne décide pas ligne par ligne, à l'exécution, si un nom est local ou global. Il le décide une fois pour toutes, à la compilation de la fonction, en scannant tout son corps pour repérer une assignation. Si une seule ligne assigne ce nom — n'importe où dans la fonction, même après un print(nom) qui le lit d'abord — ce nom devient local pour l'intégralité de la fonction, dès sa première ligne. Le print() qui précède ne remonte plus en Global : il cherche en Local, trouve une case vide, et lève UnboundLocalError.Here's the surprise most devs discover by accident: Python doesn't decide line by line, at runtime, whether a name is local or global. It decides once and for all, at the function's compile time, by scanning its whole body for an assignment. If a single line assigns that name — anywhere in the function, even after a print(name) that reads it first — that name becomes local for the function's entirety, from its very first line. The preceding print() no longer falls back to Global: it looks in Local, finds an empty slot, and raises UnboundLocalError.

Une simple lecture remonte tranquillement en GlobalA plain read quietly falls back to Global
compteur = 0

def lire():
    print(compteur)      # 0 — aucune assignation à "compteur" dans lire()
                          # -> Python le cherche direct en Global, le trouve
lire()

lire() ne contient aucune assignation à compteur — Python le classe donc directement en lecture globale, sans ambiguïté. C'est le cas confortable, celui auquel l'intuition s'attend.lire() contains no assignment to compteur — Python classes it directly as a global read, unambiguously. It's the comfortable case, the one intuition expects.

Une variable n'est pas locale « à partir de » sa ligne d'assignation. Elle l'est pour toute la fonction, ou pas du tout.A variable isn't local "starting from" its assignment line. It's local for the whole function, or not at all.
№ 03La mécaniqueThe mechanics5 min

Le classement local/global se fait une fois, à la compilation — pas à l'exécution, ligne par ligne.The local/global classification happens once, at compile time — not line by line at runtime.

Avant même le premier appel de la fonction, Python compile son corps en bytecode — et cette étape scanne l'intégralité du texte à la recherche de toute assignation. Ce n'est pas une supposition provisoire, corrigée au fil de l'exécution : c'est une décision figée dans le bytecode compilé lui-même. Une lecture de x compilée comme locale reste locale, même si la ligne d'assignation ne s'exécute jamais (un if qui ne se déclenche pas, par exemple) — le classement porte sur la présence textuelle de l'assignation, pas sur son exécution réelle.Before the function's very first call, Python compiles its body into bytecode — and that step scans the entire text for any assignment. It isn't a provisional guess, corrected as execution proceeds: it's a decision frozen into the compiled bytecode itself. A read of x compiled as local stays local, even if the assignment line never actually runs (an if that never triggers, say) — the classification is based on the assignment's textual presence, not its real execution.

Le corps entier est scanné avant le premier appelThe whole body is scanned before the first call
def f():
    print(x)          # ligne 1 : lecture de "x"
    x = 5              # ligne 2 : assignation de "x"

# à la COMPILATION de f (avant tout appel), Python scanne tout le corps :
# il trouve "x = 5" quelque part -> "x" est déclaré LOCAL pour TOUTE f
# la ligne 1 est donc compilée comme une lecture LOCALE, pas globale
# -> f.__code__.co_varnames contient "x" : c'est un fait figé, pas une supposition

Le classement n'attend pas l'exécution de la ligne 2 : il est déjà tranché quand la ligne 1 se prépare à s'exécuter. C'est visible dans f.__code__.co_varnames — la liste des noms locaux d'une fonction, calculée à la compilation, consultable avant tout appel.The classification doesn't wait for line 2 to run: it's already settled when line 1 is about to execute. It's visible in f.__code__.co_varnames — a function's list of local names, computed at compile time, inspectable before any call.

Le réflexe en une ligneThe reflex in one line

Pour savoir si un nom sera local dans une fonction, lis tout son corps — pas seulement la ligne où tu le lis.To know if a name will be local in a function, read its whole body — not just the line where you read it.

№ 04Le piègeThe trap4 min

Réassigner un nom le déclare local. Muter l'objet qu'il désigne ne fait rien de tel.Reassigning a name declares it local. Mutating the object it points to does no such thing.

Le piège le plus fréquent en pratique n'est pas une assignation explicite qu'on voit venir — c'est l'opérateur += , qui ressemble à une simple mise à jour mais se désucre en une assignation complète : total = total + valeur. Le membre de droite lit total, le signe = le réassigne : cette seule ligne suffit à déclarer total local pour toute la fonction, et la lecture qui le précède dans la même expression échoue avant même d'avoir une chance d'aboutir. Ce numéro rejoint ici le Vol. II : la même distinction entre muter en place et réassigner un nom, appliquée cette fois à la portée plutôt qu'à l'aliasing.The most frequent trap in practice isn't an explicit assignment you see coming — it's the += operator, which looks like a simple update but desugars into a full assignment: total = total + valeur. The right-hand side reads total, the = sign reassigns it: that one line is enough to declare total local for the whole function, and the read preceding it in the same expression fails before it even gets a chance to succeed. This issue meets Vol. II here: the same distinction between mutating in place and reassigning a name, applied this time to scope rather than aliasing.

total += valeur lit ET réassigne, dans la même lignetotal += valeur reads AND reassigns, in the same line
total = 0

def ajoute(valeur):
    total += valeur      # UnboundLocalError, PAS une addition sur le global
    # total += valeur se désucre en : total = total + valeur
    # c'est une ASSIGNATION -> "total" devient local pour toute la fonction
    # -> "total + valeur" essaie de LIRE le "total" local, pas encore posé

ajoute(5)

Aucun mystère une fois désucré : += lit d'abord, réassigne ensuite — mais la présence de ce =, même sucré, suffit à classer total comme local pour toute la fonction. La lecture qu'il contient devient alors une lecture locale, sur une case pas encore posée.No mystery once desugared: += reads first, reassigns after — but the presence of that =, sugared or not, is enough to classify total as local for the whole function. The read it contains then becomes a local read, on a slot not yet set.

Le contre-emploiThe counter-use

Ne conclus pas que toute lecture d'un nom externe est fragile — seule la réassignation l'est. Lire une variable englobante ou globale, sans jamais l'assigner dans la fonction, ne pose aucun problème, à n'importe quelle profondeur d'imbrication.Don't conclude that reading any outer name is fragile — only reassignment is. Reading an enclosing or global variable, without ever assigning it inside the function, poses no problem, at any nesting depth.

Le réflexe en une phraseThe reflex in one sentence

Avant d'écrire nom += ... ou nom = ... dans une fonction, demande : ce nom vit-il ailleurs, et est-ce voulu qu'il devienne local ici ? Si non, il faudra le déclarer autrement (global, nonlocal — prochains numéros).Before writing name += ... or name = ... inside a function, ask: does this name live elsewhere, and is it intended to become local here? If not, it'll need declaring another way (global, nonlocal — coming issues).

№ 05Bilan & éditoWrap-up & editorial2 min

LEGB n'est pas une recherche à l'exécution. C'est une décision prise avant que le code ne tourne.LEGB isn't a runtime search. It's a decision made before the code even runs.

Ce numéro ouvre le volume sur la portée avec un principe qui déplace l'intuition : Python ne lit pas ton code du haut vers le bas pour décider où chercher un nom. Il scanne tout le corps d'une fonction à la compilation, repère la moindre assignation, et classe le nom local pour l'intégralité de la fonction — avant la première ligne exécutée. La conséquence pratique tient en une règle : ce n'est pas la lecture d'un nom qui est fragile, c'est sa réassignation dans une fonction où on comptait lire une variable externe.This issue opens the volume on scope with a principle that shifts intuition: Python doesn't read your code top to bottom to decide where to look up a name. It scans a function's entire body at compile time, spots the slightest assignment, and classifies the name as local for the function's entirety — before the first line runs. The practical consequence boils down to one rule: it isn't reading a name that's fragile, it's reassigning it inside a function where you meant to read an outer variable.

NotionConceptCe qu'il faut en retenirWhat to take away
LEGBLocal, Enclosing, Global, Built-in — l'ordre de recherche d'un nom, fixe et non négociable.Local, Enclosing, Global, Built-in — a name's search order, fixed and non-negotiable.
UnboundLocalErrorLire un nom avant sa réassignation, dans une fonction où ce nom est assigné ailleurs — même plus bas.Reading a name before its reassignment, in a function where that name gets assigned elsewhere — even further down.
Compilation, pas exécutionCompile time, not runtimeLe classement local/global se fige en scannant tout le corps, avant le premier appel.Local/global classification freezes by scanning the whole body, before the first call.
Lire vs réassignerReading vs reassigningMuter un objet (.append()) ne déclare rien local ; réassigner le nom (=, +=) le fait, toujours.Mutating an object (.append()) declares nothing local; reassigning the name (=, +=) always does.
Un nom n'est pas local à partir d'une ligne. Il l'est pour toute la fonction — décidé avant qu'elle ne tourne.A name isn't local starting at a line. It's local for the whole function — decided before it runs.
Mot de l'éditeurFrom the editor

LEGB explique où un nom est cherché. Reste une question : quand, exactement, cette recherche a-t-elle lieu ?LEGB explains where a name is looked up. One question remains: when, exactly, does that lookup happen?

Une fonction ordinaire lit ses noms englobants au moment où elle s'exécute — immédiat, sans surprise. Mais une closure — une fonction définie à l'intérieur d'une autre, qui survit après le retour de celle-ci — capture ces noms pour un usage différé, parfois bien après que la fonction englobante a terminé. La question qui se pose alors : quand la closure lit la variable capturée, lit-elle sa valeur au moment de la définition, ou au moment de l'appel ? La réponse surprend presque tout le monde, et explique le piège le plus classique des boucles avec fonctions.An ordinary function reads its enclosing names at the moment it runs — immediate, no surprise. But a closure — a function defined inside another, that survives after the outer one returns — captures those names for later use, sometimes well after the enclosing function has finished. The question that follows: when the closure reads the captured variable, does it read its value at definition time, or at call time? The answer surprises almost everyone, and explains the classic loop-with-functions trap.

Prochain numéro : la closure capture la variable, pas la valeur. [lambda: i for i in range(3)] et le piège de la liaison tardive ; l'astuce i=i comme capture par défaut.Next issue: the closure captures the variable, not the value. [lambda: i for i in range(3)] and the late-binding trap; the i=i trick as a default-capture antidote.