Pythonの変数のスコープ入門|LEGB・global・nonlocalの使い方
Python で関数を書き始めると、「関数の中で作った変数が外から使えない」「外の変数を関数の中で 1 増やそうとしたら UnboundLocalError が出た」といったことに出会います。どちらも原因は変数のスコープ(変数の名前が通用する範囲)です。
この記事では、スコープの基本から、Python が名前を探す順番(LEGB)、global と nonlocal の使い方、そして初心者がつまずきやすい間違いまでを、実行結果つきで説明します。載せている出力は、Windows 11・Python 3.12.6 で実際に実行して確かめたものです。
コードは sample.py などの名前で保存し、PowerShell でそのフォルダーに移動してから次のコマンドで実行できます。エラーの出力にある File "C:\…\sample.py" のフォルダー部分は省略して載せています。
py sample.py
スコープとは:変数の名前が通用する範囲
スコープとは、ある変数の名前を「その名前で呼べる範囲」のことです。Python では、関数の中で作った変数は、その関数の中でしか使えません。まずは実際に確かめます。
def make_message():
message = "こんにちは"
print("関数の中:", message)
make_message()
print("関数の外:", message)
関数の中: こんにちは
Traceback (most recent call last):
File "C:\…\sample.py", line 6, in <module>
print("関数の外:", message)
^^^^^^^
NameError: name 'message' is not defined
関数の中の print は動きましたが、6 行目の関数の外の print で NameError(その名前が見つからない)になりました。message は関数 make_message の中だけで通用するローカル変数で、関数の実行が終わると使えなくなるからです。
これに対して、ファイルの一番外側(どの関数にも入っていない場所)で作った変数はグローバル変数と呼ばれ、同じファイルのどこからでも読めます。Python の公式ドキュメント(言語リファレンス 4.2「名前づけと束縛」)では、「名前がブロックの中で束縛されたら、nonlocal や global と宣言しない限り、そのブロックのローカル変数になる」と説明されています。束縛とは、名前と値(オブジェクト)を結び付けることで、代入がその代表です。
ブロックとは、まとめて実行されるプログラムのかたまりのことで、公式ドキュメントではモジュール(ファイル)・関数の本体・クラスの定義の 3 つが挙げられています。ここに if 文や for 文が入っていない点は、あとで大事になります。
名前を探す順番は LEGB
Python は、コードの中に変数の名前が出てくると、次の 4 つの範囲を内側から外側へ順に探し、最初に見つかったものを使います。頭文字をとって LEGB と呼ばれます。
| 順番 | 範囲 | どこで作られた名前か |
|---|---|---|
| 1 | L:Local(ローカル) | いま実行している関数の中 |
| 2 | E:Enclosing(外側の関数) | 関数の中に関数を書いたときの、外側の関数の中 |
| 3 | G:Global(グローバル) | ファイル(モジュール)の一番外側 |
| 4 | B:Built-in(組み込み) | print・len・list など最初から使える名前 |

公式チュートリアル 9.2「Python のスコープと名前空間」でも、最初に探すのはローカルの名前、次に外側の関数を近い順に、その次がモジュールのグローバルな名前、最後が組み込みの名前、と説明されています。どこにも見つからなければ NameError です。
同じ x という名前を 3 か所で作って、どれが使われるかを見てみます。
x = "global の x"
def outer():
x = "outer の x"
def inner():
x = "inner の x"
print("inner:", x)
inner()
print("outer:", x)
outer()
print("module:", x)
inner: inner の x
outer: outer の x
module: global の x
それぞれの場所で、一番近い x が使われています。3 つの x は名前が同じだけの別々の変数で、inner の中で代入しても外の x は変わりません。
次に、inner の中の代入を消して、読むだけにします。
x = "global の x"
def outer():
x = "outer の x"
def inner():
print("inner:", x)
inner()
outer()
def show():
print("show:", x, len("abc"))
show()
inner: outer の x
show: global の x 3
inner の中には x がないので、1 つ外側の outer の x(E)が見つかりました。show の中では、外側の関数がないのでグローバルの x(G)が使われ、len は組み込み(B)から見つかっています。
関数の中で外の変数に代入するとどうなるか
読むのはできるが、代入すると別のローカル変数になる
外の変数を読むだけなら、上のように関数の中から問題なく使えます。ところが、関数の中で同じ名前に代入すると、それは外の変数の書き換えではなく、新しいローカル変数を作ることになります。
count = 0
def add():
count = 100
print("関数の中:", count)
add()
print("関数の外:", count)
関数の中: 100
関数の外: 0
関数の中では 100 になっていますが、外の count は 0 のままです。公式チュートリアルにも、外側の変数は宣言しなければ読み取り専用で、書き込もうとすると「いちばん内側のスコープに新しいローカル変数を作るだけで、同じ名前の外側の変数は変わらない」と書かれています。
読んでから代入すると UnboundLocalError
ここで多くの人がつまずくのが次のコードです。外の count を表示してから 1 増やすつもりです。
count = 0
def increment():
print("今の値:", count)
count += 1
increment()
Traceback (most recent call last):
File "C:\…\sample.py", line 7, in <module>
increment()
File "C:\…\sample.py", line 4, in increment
print("今の値:", count)
^^^^^
UnboundLocalError: cannot access local variable 'count' where it is not associated with a value
エラーの文は「ローカル変数 count には、まだ値が結び付いていないので使えない」という意味です。外に count = 0 があるのに、なぜでしょうか。
理由は、Python が関数を実行する前に、関数の中で代入されている名前をローカル変数と決めてしまうからです。count += 1 は count = count + 1 と同じく代入なので、increment の中の count は、5 行目だけでなく 4 行目も含めてすべてローカル変数として扱われます。4 行目の時点ではそのローカル変数にまだ値がないので、エラーになります。言語リファレンスでも「ブロックのどこかで名前の束縛があれば、ブロック内のその名前の使用はすべて現在のブロックへの参照として扱われる」と説明されています。
代入の行が実行されるかどうかは関係ありません。次のように、決して実行されない if False: の中に代入があるだけでも同じエラーになります。
x = 10
def f():
print(x)
if False:
x = 1
f()
UnboundLocalError: cannot access local variable 'x' where it is not associated with a value
(Traceback の部分は省略しています。)UnboundLocalError は NameError の一種(サブクラス)なので、except NameError でも捕まえられます。ただ、これはプログラムの書き方の間違いなので、例外処理でごまかさず、次の方法で直します。
global 文で外の変数を書き換える
関数の中から本当にグローバル変数を書き換えたいときは、関数の先頭で global 名前 と宣言します。
count = 0
def increment():
global count
count += 1
increment()
increment()
print(count)
2
global count と書いたので、関数の中の count はローカル変数ではなく、グローバルの count そのものを指すようになりました。global 文は、その名前を使うより前に書く必要があります(公式ドキュメントに「global 文は、並べた名前のすべての使用より前になければならない」とあります)。
global を多用しないほうがよい理由
global は便利ですが、使う場所が増えるほどプログラムが読みにくくなります。
- どの関数がいつ値を変えたのかを追いにくい。バグの原因を探すとき、関数の中だけ見ても分からない
- 関数を呼ぶ順番や回数で結果が変わるので、テストしにくい
- 同じ関数を別の目的で使い回しにくい(グローバル変数が 1 つしかないため)
公式の FAQ も、代入する変数に global を求めるのは「意図しない副作用を防ぐ歯止め」になるからだと説明しています。global と書いてある場所は「ここで外の値を変えている」という目印なので、なるべく少なく保つのがよい書き方です。
代わりの書き方:引数で受け取り、戻り値で返す
多くの場合は、値を引数で受け取り、新しい値を戻り値で返すようにすれば global はいりません。
def increment(count):
return count + 1
count = 0
count = increment(count)
count = increment(count)
print(count)
2
結果は同じですが、increment は「受け取った数に 1 を足して返す」だけの関数になり、外の変数に依存しません。値を変えているのは呼び出し側の代入(count = …)だけなので、どこで値が変わったかがひと目で分かります。テストも assert increment(0) == 1 のように簡単に書けます。
いくつもの値をまとめて持ち回りたいときは、クラスや辞書にまとめて引数で渡す方法もあります。
nonlocal で外側の関数の変数を書き換える
関数の中に関数を書いたとき、内側の関数から外側の関数の変数(LEGB の E)を書き換えるには nonlocal を使います。代表的な例が、呼ぶたびに 1 ずつ増えるカウンターです。
def make_counter():
count = 0
def counter():
nonlocal count
count += 1
return count
return counter
c1 = make_counter()
c2 = make_counter()
print(c1(), c1(), c1())
print(c2())
1 2 3
1
make_counter は、中で作った関数 counter を返します。返された counter は、make_counter の実行が終わったあとも外側の count を覚えていて、呼ぶたびに増やします。このように外側の変数を覚えている関数をクロージャと呼びます。c1 と c2 はそれぞれ別の count を持っているので、c2() は 1 から始まっています。グローバル変数を使わずに「状態を持つ関数」が作れるのが利点です。
nonlocal count の行を消すと、さきほどと同じ理由でエラーになります。
Traceback (most recent call last):
File "C:\…\sample.py", line 9, in <module>
c()
File "C:\…\sample.py", line 4, in counter
count += 1
^^^^^
UnboundLocalError: cannot access local variable 'count' where it is not associated with a value
(このときのコードは、上のカウンターから nonlocal count の行を消し、最後を c = make_counter() と c() の 2 行にしたものです。)
nonlocal が探すのは外側の関数の中だけで、グローバル変数は対象になりません。外側の関数にその名前がないと、実行する前に SyntaxError: no binding for nonlocal 'x' found になります。
| 宣言 | 書き換える対象 | 主な使いどころ |
|---|---|---|
| なし | (代入すると新しいローカル変数になる) | ふつうの関数 |
global x | ファイルの一番外側の x | 設定値の切り替えなど、どうしても必要なときだけ |
nonlocal x | いちばん近い外側の関数の x | クロージャ(カウンター、デコレーターの中など) |
クロージャはデコレーターの中でもよく使われます。仕組みは関連記事「Pythonのデコレーター入門」で詳しく説明しています。なお、カウンターのように「呼ぶたびに続きから値を出す」処理は、ジェネレーター(yield)で書けることもあります。
リストの append には global がいらない
グローバルのリストに関数の中で要素を足すとき、global を書かなくても動きます。
items = []
def add_item(name):
items.append(name)
add_item("りんご")
add_item("みかん")
print(items)
def reset():
items = []
reset()
print(items)
['りんご', 'みかん']
['りんご', 'みかん']
items.append(name) は、items という名前が指しているリストの中身を変える操作で、items という名前への代入ではありません。関数の中で items は読んでいるだけなので、LEGB の順でグローバルのリストが見つかり、そのリストに要素が足されます。辞書の config["debug"] = True のような要素への代入も同じで、global はいりません。
一方、reset の中の items = [] は名前への代入なので、新しいローカル変数ができるだけで、グローバルのリストは空になっていません。空にしたいなら items.clear() を使うか、global items を宣言します。
「名前に別のものを付け直す(代入)」と「名前が指しているものの中身を変える(append など)」の違いは、リストのコピーで起きる問題と同じ考え方です。関連記事「Pythonの浅いコピーと深いコピー」もあわせて読むと理解が深まります。
よくある間違い
組み込み関数の名前を変数名に使ってしまう
list・dict・str・sum・max・id などは組み込み(LEGB の B)の名前です。同じ名前の変数を作ると、LEGB の順でその変数が先に見つかるため、組み込み関数が使えなくなります。
list = [3, 1, 2]
print(list)
numbers = list((4, 5, 6))
[3, 1, 2]
Traceback (most recent call last):
File "C:\…\sample.py", line 3, in <module>
numbers = list((4, 5, 6))
^^^^^^^^^^^^^^^
TypeError: 'list' object is not callable
「list オブジェクトは呼び出せない」というエラーです。3 行目の list は、組み込みの list 関数ではなく、1 行目で作ったリスト [3, 1, 2] を指しています。組み込みの list が消えたわけではなく、グローバル変数に隠されているだけなので、del list でその変数を消すと元どおり使えます(del list のあとの list((4, 5, 6)) は [4, 5, 6] を返しました)。
いちばんよい直し方は、numbers・items・user_list のように、組み込みと重ならない名前を付けることです。とくに対話モード(py と入力して起動する画面)で一度 list = … と書くと、del list とするか画面を閉じるまで list() が使えないままになります。
for 文や if 文の中の変数がブロックの外でも残る
Python では、for 文・if 文・while 文・with 文はスコープを作りません。中で作った変数は、ブロックが終わったあとも使えます。
for i in range(3):
last = i * 10
print("ループのあと i =", i, "last =", last)
if True:
inside_if = "if の中で作った"
print(inside_if)
squares = [n * n for n in range(3)]
print(squares)
print(n)
ループのあと i = 2 last = 20
if の中で作った
[0, 1, 4]
Traceback (most recent call last):
File "C:\…\sample.py", line 11, in <module>
print(n)
^
NameError: name 'n' is not defined
ループ変数 i はループが終わったあとも最後の値 2 のまま残っています。C 言語や Java、JavaScript の let では、ブロックの中の変数は外から見えないので、ほかの言語から来た人は驚くところです。ループの外で i をうっかり使っても、エラーにならずに古い値で動いてしまう点に注意してください。
ただし、11 行目のとおり、内包表記([n * n for n in range(3)] など)は独自のスコープを持ちます。内包表記の中の n は外に漏れません。外に同じ名前の変数があっても上書きされないことも確かめました。
n = "外の n"
squares = [n * 2 for n in range(3)]
print(squares, n)
[0, 2, 4] 外の n
クラスの本体で作った変数はメソッドから直接見えない
クラスの本体もスコープの一種ですが、少し特殊です。クラスの本体で作った変数(クラス変数)は、メソッドの中から名前だけでは見えません。
class Shop:
tax = 10
def price(self, base):
return base + base * tax // 100
print(Shop().price(1000))
Traceback (most recent call last):
File "C:\…\sample.py", line 6, in <module>
print(Shop().price(1000))
^^^^^^^^^^^^^^^^^^
File "C:\…\sample.py", line 4, in price
return base + base * tax // 100
^^^
NameError: name 'tax' is not defined. Did you mean: 'self.tax'?
言語リファレンスにも「クラスのブロックで定義した名前のスコープはクラスのブロックの中に限られ、メソッドのコードブロックには及ばない」とあります。LEGB の E に含まれるのは外側の関数だけで、クラスは含まれません。エラーメッセージが提案しているとおり self.tax(または Shop.tax)と書けば、1100 と表示されます。
よくある質問
関数の中からグローバル変数を読むときも global が必要ですか?
いりません。読むだけなら LEGB の順で自動的に見つかります。global が必要なのは、関数の中でその名前に代入するときだけです。公式の FAQ でも、関数の中で参照されるだけの変数は暗黙にグローバルとして扱われ、関数の本体のどこかで代入される変数はローカルとみなされる、と説明されています。
いまどんな変数が見えているか確かめる方法はありますか?
組み込み関数 locals() はローカル変数の辞書を、globals() はグローバル変数の辞書を返します。たとえば関数の中で x = 1 のあとに print(locals()) とすると {'x': 1} と表示されました。デバッグのときに役立ちます。
global と nonlocal を同じ名前に書けますか?
同じ関数の中で 1 つの名前に両方は書けません。書くと SyntaxError: name 'x' is nonlocal and global になりました。また、内側の関数で global x と書くと、外側の関数の x ではなく、ファイルの一番外側の x が書き換わります。外側の関数の変数を書き換えたいときは nonlocal です。
UnboundLocalError を try / except で防いでもよいですか?
おすすめしません。原因は「関数の中で代入している名前を、代入より前に読んでいる」という書き方の問題なので、引数と戻り値で受け渡すか、必要なら global・nonlocal を宣言して直します。例外処理の考え方は関連記事「Pythonの例外処理入門」で解説しています。
まとめ
- 関数の中で作った変数はローカル変数で、関数の外からは使えない
- 名前は Local → Enclosing → Global → Built-in の順(LEGB)で探される
- 関数の中で代入した名前はローカル変数になる。代入より前に読むと
UnboundLocalError - グローバル変数の書き換えは
global、外側の関数の変数はnonlocal。ただし、まずは引数と戻り値で書けないか考える appendなどの中身の変更は代入ではないのでglobalはいらないlistなどの組み込みの名前を変数名にしない。for 文や if 文はスコープを作らないが、内包表記は作る
関連する記事・ツール
- Pythonのデコレーター入門|@の仕組みとfunctools.wrapsを実例で解説
- Pythonのジェネレーターとyieldの使い方|イテレーターの仕組みとメモリ節約を実例で解説
- Pythonの浅いコピーと深いコピー|copy・deepcopyの違いとよくある間違い
- Pythonの例外処理入門|try・except・finally・raiseの使い方
- Pythonのリスト・辞書・内包表記の基本|使い方とよくある間違いを実例で解説
- Pythonのテスト入門|unittestとpytestの書き方・実行方法を実例で比較