PythonのEnum(列挙型)の使い方|name・value・StrEnumを実例で解説
ユーザーの状態を "active"・"suspended" のような文字列で表していると、どこかで "actve" と打ち間違えても、エラーにならずに動き続けてしまいます。Python の Enum(イーナム、列挙型)を使うと、取りうる値を 1 か所にまとめて名前を付けられ、打ち間違いはすぐにエラーになります。標準ライブラリの enum モジュールに入っているので、インストールは不要です。
この記事では、Enum の基本(name と value、値や名前からメンバーを取り出す方法)、IntEnum・StrEnum との違い、auto()・@unique・Flag、JSON にするときのエラー、match 文や dataclass と組み合わせる例までを順に説明します。載せている出力は、Windows 11・Python 3.12.6 で実際に実行して確かめたものです。
文字列の定数で困ること
まず Enum を使わずに、「状態が active ならログインできる」という関数を書いてみます。次のコードを sample.py という名前で保存します。
def can_login(status):
return status == "active"
print(can_login("active"))
print(can_login("actve"))
PowerShell で、sample.py を保存したフォルダーに移動してから実行します。
py sample.py
True
False
2 行目は打ち間違いなのに、エラーではなく「ログインできない(False)」という普通の結果が返っています。こうした間違いはテストで偶然見つかるまで気づけません。ほかにも、次のような困りごとがあります。
- どんな値がありうるのか、コードのあちこちを探さないと分からない
- 数値で表している場合(1=有効、2=停止 など)、
if status == 2を読んでも意味が分からない - エディターの入力補完が効かない
Enum で書き直す
同じ内容を Enum で書くと次のようになります。Enum を継承したクラスを作り、名前 = 値 の形で並べます。この 1 つ 1 つをメンバーと呼びます。名前は定数なので、慣習として大文字で書きます。
from enum import Enum
class Status(Enum):
ACTIVE = "active"
SUSPENDED = "suspended"
DELETED = "deleted"
def can_login(status: Status) -> bool:
return status is Status.ACTIVE
print(can_login(Status.ACTIVE))
print(Status.ACTVE)
True
Traceback (most recent call last):
...
AttributeError: type object 'Status' has no attribute 'ACTVE'. Did you mean: 'ACTIVE'?
打ち間違えた Status.ACTVE は、その行を実行した時点で AttributeError になり、「ACTIVE のことですか?」と候補まで出ます。ありうる値はクラスを見れば一覧でき、エディターでも Status. と打てば候補が表示されます。
なお、関数の引数に付けた status: Status は型ヒントで、実行時のチェックはしません。can_login("active") と文字列を渡すと、エラーにならずに False が返りました。型の間違いまで見つけたいときは、型チェッカーと組み合わせます(「Pythonの型ヒント入門」参照)。
メンバーの name と value
公式ドキュメントでは、Enum は「一意の値に結び付けられた、名前(メンバー)の集まり」と説明されています。メンバーは name(名前)と value(値)の 2 つを持ちます。色を例に確かめます。
from enum import Enum
class Color(Enum):
RED = 1
GREEN = 2
BLUE = 3
print(Color.RED)
print(repr(Color.RED))
print(Color.RED.name, Color.RED.value)
print(type(Color.RED))
print(Color(1))
print(Color["RED"])
Color.RED
<Color.RED: 1>
RED 1
<enum 'Color'>
Color.RED
Color.RED
Color.RED.nameは名前の文字列'RED'、Color.RED.valueは値の1Color.RED自体は 1 ではなく、Color 型のオブジェクトColor(1)で値から、Color["RED"]で名前からメンバーを取り出せる。どちらも同じColor.REDが返る

Color(1) は、データベースや設定ファイルから読んだ数値・文字列を Enum に変換するときに使います。Color["RED"] は、画面やコマンドラインで名前を受け取るときに便利です。
存在しない値・名前を指定したとき
どちらも、ないものを指定するとエラーになります。種類が違う点に注意してください。
| 書き方 | 出たエラー |
|---|---|
Color(5) | ValueError: 5 is not a valid Color |
Color["PINK"] | KeyError: 'PINK' |
外から来た値を変換するときは、try・except ValueError で受け止めて「不正な値です」と知らせると安全です(「Pythonの例外処理入門」参照)。大文字小文字も区別されるので、Status("ACTIVE") は ValueError: 'ACTIVE' is not a valid Status になりました(値は小文字の “active” のため)。
エラーを出さずに「その値があるか」だけ調べたいときは、in が使えます。Python 3.12 で "active" in Status を実行すると True、"actve" in Status は False でした。公式ドキュメントには「Python 3.12 より前は、メンバーでないものを in で調べると TypeError になる」とあるので、3.11 以前では Status(s) を try で囲む方法を使います。
for で順に取り出す・len で数える
Enum クラスはそのまま for で回せます。順番は書いた順です。
print(len(Color))
for c in Color:
print(c.name, c.value)
print(list(Color))
3
RED 1
GREEN 2
BLUE 3
[<Color.RED: 1>, <Color.GREEN: 2>, <Color.BLUE: 3>]
プルダウンの選択肢を作る、ヘルプに使える値を並べる、といった場面で使えます。また、メンバーはあとから書き換えられません。Color.RED = 5 は AttributeError: cannot reassign member 'RED' になりました。
比較は is か ==。生の値とは等しくならない
公式の Enum HOWTO には「メンバーは同一性(is)で比較される」とあります。メンバーはそれぞれ 1 つしか作られないので、is でも == でも正しく比べられます。注意したいのは、普通の Enum のメンバーは、元の値(1 や “active”)とは == で等しくならないことです。一方、IntEnum と StrEnum(Python 3.11 で追加)は、メンバーが int や str としても振る舞うので等しくなります。
from enum import Enum, IntEnum, StrEnum
class Color(Enum):
RED = 1
class Priority(IntEnum):
LOW = 1
HIGH = 2
class Status(StrEnum):
ACTIVE = "active"
print(Color.RED == 1, Color.RED.value == 1, Color.RED is Color.RED)
print(Priority.LOW == 1, Priority.HIGH > Priority.LOW, Priority.LOW + 10)
print(Status.ACTIVE == "active", Status.ACTIVE.upper())
print(f"{Color.RED} / {Priority.LOW} / {Status.ACTIVE}")
False True True
True True 11
True ACTIVE
Color.RED / 1 / active
| 種類 | 生の値と == | 大小の比較 | f 文字列での表示 | 向いている場面 |
|---|---|---|---|---|
| Enum | False(.value で比べる) | できない(TypeError) | Color.RED | 基本はこれ。うっかり数値・文字列と混ざらない |
| IntEnum | True | できる | 1 | 既存の数値定数を置き換える、優先度のように大小がある |
| StrEnum(3.11〜) | True | 文字列として比較 | active | 文字列を受け取る既存の関数・JSON とやり取りする |
普通の Enum で Color.RED < Color.GREEN と書くと、TypeError: '<' not supported between instances of 'Color' and 'Color' になりました。IntEnum では Priority.LOW + 10 が 11 になるように、計算結果は Enum ではなくただの数値になります(公式ドキュメントにも「整数の演算をすると結果は列挙型でなくなる」とあります)。f 文字列での表示が値になるのは、Python 3.11 で IntEnum の __str__ が int のものに変わったためです。
便利そうに見えますが、IntEnum・StrEnum は「別の種類の値と間違えて比べてもエラーにならない」という、文字列定数と同じ弱点を一部持ち込みます。公式の Enum HOWTO でも、新しいコードでは Enum と Flag を強く勧め、IntEnum・IntFlag は「整数の定数を置き換えるときや、ほかのシステムとやり取りするときなど、Enum では足りない場合だけ」に使うよう書かれています。
auto() で値を自動で付ける
値そのものに意味がなく、区別できればよいだけなら、auto() で値を自動で振れます。
from enum import Enum, StrEnum, auto
class Weekday(Enum):
MONDAY = auto()
TUESDAY = auto()
WEDNESDAY = auto()
class Level(StrEnum):
DEBUG = auto()
INFO = auto()
print(list(Weekday))
print(list(Level))
[<Weekday.MONDAY: 1>, <Weekday.TUESDAY: 2>, <Weekday.WEDNESDAY: 3>]
[<Level.DEBUG: 'debug'>, <Level.INFO: 'info'>]
公式ドキュメントによると、auto() が付ける値は、Enum と IntEnum では「それまでの最大値+1」、Flag では「次の 2 の累乗」、StrEnum では「メンバー名を小文字にしたもの」です。ただし、値をデータベースやファイルに保存する場合は、auto() は避けて値を直接書くほうが安全です。途中にメンバーを足すと、後ろのメンバーの値がずれてしまい、保存済みのデータと合わなくなるためです。
値が重複すると「別名」になる。@unique で防ぐ
値をコピーして貼り付けたときなどに、うっかり同じ値を 2 回書いてしまうことがあります。Enum はこれをエラーにせず、あとのメンバーを前のメンバーの別名(エイリアス)として扱います。
from enum import Enum
class Status(Enum):
ACTIVE = 1
SUSPENDED = 2
DELETED = 2
print(Status.DELETED)
print(Status.DELETED is Status.SUSPENDED)
print(list(Status))
print(list(Status.__members__))
Status.SUSPENDED
True
[<Status.ACTIVE: 1>, <Status.SUSPENDED: 2>]
['ACTIVE', 'SUSPENDED', 'DELETED']
Status.DELETED を指定したのに Status.SUSPENDED が返り、for で回しても DELETED は出てきません。「削除済みのユーザー」が「停止中」として扱われる、気づきにくいバグになります。別名をすべて含めた一覧は __members__ で見られます。
重複を許したくないときは、クラスに @unique デコレーターを付けます。重複があると、クラスを作った時点で止まります。
from enum import Enum, unique
@unique
class Status(Enum):
ACTIVE = 1
SUSPENDED = 2
DELETED = 2
Traceback (most recent call last):
...
ValueError: duplicate values found in <enum 'Status'>: DELETED -> SUSPENDED
「DELETED が SUSPENDED と重複している」と教えてくれます。値を手で書く Enum には、付けておくと安心です。@ の仕組みは「Pythonのデコレーター入門」で解説しています。
メソッドやプロパティを足す
Enum もクラスなので、メソッドを書けます。メソッドの中の self は各メンバーです。値をタプルにして __init__ で受け取ると、メンバーごとに複数の情報を持たせることもできます。
from enum import Enum
class Plan(Enum):
FREE = ("無料", 0)
PRO = ("プロ", 980)
def __init__(self, label, price):
self.label = label
self.price = price
@property
def is_paid(self):
return self.price > 0
def describe(self):
return f"{self.label}プラン(月 {self.price} 円)"
for p in Plan:
print(p.name, p.value, p.is_paid, p.describe())
FREE ('無料', 0) False 無料プラン(月 0 円)
PRO ('プロ', 980) True プロプラン(月 980 円)
value はタプル全体になり、label と price で個別に取り出せます。「有料かどうか」のような判定を Enum の中にまとめておくと、if plan == Plan.PRO or ... のような条件がコードのあちこちに散らばらずに済みます。
Flag で組み合わせを表す
「読み取り+書き込み」のように、複数を同時に選べる設定には Flag を使います。Flag のメンバーは |(または)でまとめられ、in で「含まれているか」を調べられます。
from enum import Flag, auto
class Perm(Flag):
READ = auto()
WRITE = auto()
EXECUTE = auto()
print([(p.name, p.value) for p in Perm])
rw = Perm.READ | Perm.WRITE
print(rw)
print(rw.value)
print(Perm.WRITE in rw, Perm.EXECUTE in rw)
rw |= Perm.EXECUTE
print(rw)
[('READ', 1), ('WRITE', 2), ('EXECUTE', 4)]
Perm.READ|WRITE
3
True False
Perm.READ|WRITE|EXECUTE
auto() で 1・2・4 と 2 の累乗が振られ、READ|WRITE は 1+2=3 という 1 つの値になります。中身は 2 進数のビットの組み合わせで、Linux のファイル権限(r=4、w=2、x=1)と同じ考え方です。ビットの仕組みは「ビット演算の基本」で詳しく解説しています。
JSON にするときは .value を使う
普通の Enum のメンバーは、そのままでは json.dumps に渡せません。
import json
from enum import Enum
class Color(Enum):
RED = 1
print(json.dumps({"color": Color.RED.value}))
json.dumps({"color": Color.RED})
{"color": 1}
Traceback (most recent call last):
...
TypeError: Object of type Color is not JSON serializable
.value を付けて値を渡せば JSON にできます。一方、IntEnum・StrEnum は int・str の仲間なので、そのまま渡しても数値・文字列として書き出されました。JSON から読み込んだ値は、Status(data["status"]) で Enum に戻せます。
import json
from enum import IntEnum, StrEnum
class Priority(IntEnum):
HIGH = 2
class Status(StrEnum):
ACTIVE = "active"
print(json.dumps({"priority": Priority.HIGH, "status": Status.ACTIVE}))
data = json.loads('{"status": "active"}')
print(repr(Status(data["status"])))
{"priority": 2, "status": "active"}
<Status.ACTIVE: 'active'>
json モジュールの使い方は「PythonでJSONを扱う方法」を参照してください。書き出した JSON の形を確かめたいときは、JSON整形ツールに貼り付けると、インデントを付けて見やすく表示できます。
match 文と組み合わせる
Python 3.10 から使える match 文では、case Status.ACTIVE: のようにメンバーをそのまま書けます。| で複数のメンバーをまとめることもできます。
from enum import Enum
class Status(Enum):
ACTIVE = "active"
SUSPENDED = "suspended"
DELETED = "deleted"
def message(status: Status) -> str:
match status:
case Status.ACTIVE:
return "ログインできます"
case Status.SUSPENDED | Status.DELETED:
return "ログインできません"
for s in Status:
print(s.value, message(s))
active ログインできます
suspended ログインできません
deleted ログインできません
if・elif を並べるより、どの状態でどうなるかが一目で分かります。for で全メンバーを回して結果を確かめると、メンバーを追加したときの書き漏れにも気づけます(書き漏れたメンバーでは、この関数は何も返さず None になります)。
dataclass や型ヒントと一緒に使う
dataclass のフィールドの型に Enum を使うと、「この項目に入るのは決まった値のどれか」がクラスの定義から分かるようになります。
from dataclasses import dataclass, asdict
from enum import Enum
import json
class Status(Enum):
ACTIVE = "active"
SUSPENDED = "suspended"
@dataclass
class User:
name: str
status: Status = Status.ACTIVE
u = User("田中")
print(u)
d = asdict(u)
print(d)
d["status"] = d["status"].value
print(json.dumps(d, ensure_ascii=False))
print(User("佐藤", Status("suspended")))
User(name='田中', status=<Status.ACTIVE: 'active'>)
{'name': '田中', 'status': <Status.ACTIVE: 'active'>}
{"name": "田中", "status": "active"}
User(name='佐藤', status=<Status.SUSPENDED: 'suspended'>)
Enum のメンバーは変更できない値なので、status: Status = Status.ACTIVE のように既定値にそのまま書けます(リストのように default_factory を使う必要はありません)。asdict は Enum を値に変えてくれないため、JSON にする前に .value に置き換えています。dataclass の基本は「Pythonのdataclassの使い方」で解説しています。
よくある間違い
| 書いたコード | 起きること | 直し方 |
|---|---|---|
if status == "active":(status は Enum) | 常に False になる | status is Status.ACTIVE か status.value == "active" |
Color("RED") | ValueError(”RED” は値ではなく名前) | 名前からなら Color["RED"] |
| 値の重複 | あとのメンバーが別名になり、for にも出ない | @unique を付ける |
json.dumps(Color.RED) | TypeError | Color.RED.value を渡す |
保存する値に auto() | 途中にメンバーを足すと値がずれる | 値を直接書く |
よくある質問
StrEnum が使えないと言われます
StrEnum は Python 3.11 で追加されたので、3.10 以前では ImportError になります。py --version でバージョンを確かめてください。古いバージョンでは、class Status(str, Enum): のように str と Enum を両方継承する書き方がよく使われますが、f 文字列での表示が StrEnum と異なります。Python 3.12 で試すと、class S(str, Enum) のメンバーは f"{S.A}" が S.A になり、StrEnum では値の active になりました(どちらも == "active" は True)。
Enum と辞書(dict)はどう使い分けますか?
「取りうる値が決まっていて、プログラムの中で名前で区別したい」なら Enum、「キーがあとから増える・外から読み込む」なら辞書が向いています。Enum の定数に表示名などの情報を付けたいときは、上の Plan の例のようにメソッドやタプルの値を使えます。辞書の基本は「Pythonのリスト・辞書・内包表記の基本」を参照してください。
まとめ
- Enum は決まった値の集まりに名前を付ける仕組み。打ち間違いはすぐ AttributeError になる
- メンバーは
nameとvalueを持つ。値からはColor(1)、名前からはColor["RED"] - 普通の Enum は生の値と
==で等しくならない。IntEnum・StrEnum は等しくなる - 値の重複は別名になるので
@uniqueで防ぐ。組み合わせには Flag - JSON にするときは
.valueを使う
関連する記事・ツール
- JSON整形ツール
- Pythonのdataclassの使い方|既定値・frozen・asdictを実例で解説
- Pythonの型ヒント入門|typingの書き方とmypyで型の間違いを見つける方法
- PythonでJSONを扱う方法|json.loads・dumpsの使い方とエラー対処
- Pythonのデコレーター入門|@の仕組みとfunctools.wrapsを実例で解説
- ビット演算の基本と実用例|AND・OR・XOR・シフトとフラグ・マスクの使い方
- Pythonのmatch文の使い方|パターンマッチとcase RED:の落とし穴