Python enum — Members, auto, IntEnum, and StrEnum
A fixed set of named choices, written as bare numbers or text in a program, is hard to read and easy to mistype. The enum module gives the set a class, gives each choice a name and a value, and makes a wrong lookup fail at once instead of passing a bad value downstream. This guide takes plain members first, then the text and number forms, aliases, flags, the functional call, and the lookup traps.
Written November 13, 2026 · Tested with Python 3.12.3 · 9 min read
- The main program: members, names, and values
- StrEnum: members that are the text
- IntEnum: members that compare as numbers
- Aliases: a second name for one member
Written November 13, 2026
Tested with Python 3.12.3
What this guide is
An enumeration is a class whose members are the only values of that kind in the program. Each member has a name, written in capitals by convention, and a value that the program rarely reads directly. Code passes the member itself around, compares members with is or ==, and prints the member by its class and name. A lookup with a value or a name that the class does not hold raises an error on the spot, which is the point: a bad state fails where it enters, not three calls later as a number nobody recognizes.
The main program: members, names, and values
The auto call assigns values in order, starting at 1. A member prints as its class and name. The name and value attributes read the two parts back, and two call forms look a member up: the class called with a value, and the class indexed with a name:
from enum import Enum, auto
class Color(Enum):
RED = auto()
GREEN = auto()
BLUE = auto()
print(list(Color))
print(Color.RED)
print(Color.RED.name, Color.RED.value)
print(Color(2))
print(Color["BLUE"])
print(Color(2) is Color.GREEN)
print(len(Color))
The exact output:
[<Color.RED: 1>, <Color.GREEN: 2>, <Color.BLUE: 3>]
Color.RED
RED 1
Color.GREEN
Color.BLUE
True
3
Listing the class gives the members in definition order. The lookup by value and the lookup by name return the same member objects the class defines, so the identity test with is passes: there is exactly one Color.GREEN in the program, however it was reached. The length counts members, and a member test or a comparison in running code uses the member itself, not its number.
StrEnum: members that are the text
A StrEnum member is a string whose value, with auto, is the member name in lower case. Printing a member, formatting it into text, and comparing it with plain text all use that value, so a member can go straight into a message, a file, or a stored record without a conversion step:
from enum import StrEnum, auto
class Season(StrEnum):
SPRING = auto()
SUMMER = auto()
FALL = auto()
WINTER = auto()
print(Season.SPRING)
print(Season.SPRING.value)
print(str(Season.SUMMER))
print(f"{Season.FALL}")
print(Season.WINTER == "winter")
print(Season.WINTER == Season.WINTER)
The exact output:
spring
spring
summer
fall
True
True
The equality with the plain text "winter" is the reason to pick this form: data read back as text compares equal to the member, so a value stored as text and a member in code meet without a lookup in between. A plain Enum member does not do this. Its printed form keeps the class name, and it never equals its own value.
IntEnum: members that compare as numbers
An IntEnum member is an integer as well as a member. It equals its value, it orders against other members and against plain numbers, and it takes part in arithmetic, with the result a plain integer rather than a member. Status codes and levels that arrive as numbers from outside the program are the natural fit:
from enum import IntEnum
class Status(IntEnum):
OK = 200
NOT_FOUND = 404
ERROR = 500
print(Status.OK == 200)
print(int(Status.NOT_FOUND))
print(Status.ERROR > Status.OK)
print(sorted([Status.ERROR, Status.OK, Status.NOT_FOUND]))
print(Status.OK + 1)
print(type(Status.OK) is Status)
The exact output:
True
404
True
[<Status.OK: 200>, <Status.NOT_FOUND: 404>, <Status.ERROR: 500>]
201
True
Sorting works here because the members are numbers; a plain Enum raises an error on the same comparison, as the last section shows. The arithmetic line is the boundary to note: 200 plus 1 is 201, a plain integer with no member attached. Code that needs the result back as a member looks it up by value, and a result with no matching member fails that lookup.
Aliases: a second name for one member
Two names with the same value do not make two members. The second name becomes an alias for the first: it is the same object, it does not appear when the class is listed or counted, and it does appear in the members mapping. The unique decorator turns that quiet alias into an error at class definition, for enums where a repeated value is a mistake rather than a second spelling:
from enum import Enum, unique
class Day(Enum):
MONDAY = 1
TUESDAY = 2
MON = 1
print(Day.MON is Day.MONDAY)
print(list(Day))
print(len(Day))
print(list(Day.__members__))
try:
@unique
class Bad(Enum):
A = 1
B = 1
print("no error")
except ValueError as e:
print("ValueError")
The exact output:
True
[<Day.MONDAY: 1>, <Day.TUESDAY: 2>]
2
['MONDAY', 'TUESDAY', 'MON']
ValueError
The count is 2, not 3, and the listing holds the two real members only, while the mapping holds all three names. That split explains code that iterates an enum and never sees the alias it defined. Aliases are for a second spelling of one choice; a distinct choice needs its own value.
IntFlag: choices that combine
A flag member stands for one bit, and members combine with the or operator into a set of choices held in one value. The in test asks whether one flag is part of a combination. An IntFlag combination prints as its number in this Python version, so code reads the parts back by testing or listing, not by reading the printed form:
from enum import Flag, IntFlag, auto
class Perm(IntFlag):
READ = auto()
WRITE = auto()
EXECUTE = auto()
both = Perm.READ | Perm.WRITE
print(both)
print(list(both))
print(Perm.READ in both)
print(Perm.EXECUTE in both)
print(both.value)
print(Perm(3) is both)
print(Perm(0))
print(bool(Perm(0)))
The exact output:
3
[<Perm.READ: 1>, <Perm.WRITE: 2>]
True
False
3
True
0
False
Listing the combination gives the single flags it holds, in definition order. The empty combination, value 0, is the one flag value that reads as false, which makes a plain truth test on the whole set meaningful: a combination with any flag set reads as true, and the empty one reads as false. Permissions, options, and feature switches follow this shape, one flag per choice and combinations wherever the choices overlap.
The functional call: building the class in one line
An enum can be built by calling the Enum class with a name and a list of member names, which suits a set of names the program holds as data. Values with auto numbering follow the list order. The IntEnum call takes a mapping of names to values when the numbers carry meaning of their own:
from enum import Enum, IntEnum
Animal = Enum("Animal", ["ANT", "BEE", "CAT"])
print(list(Animal))
print(Animal.BEE.value)
Size = IntEnum("Size", {"SMALL": 1, "MEDIUM": 2, "LARGE": 3})
print(Size.MEDIUM == 2)
print(Size["LARGE"].value)
The exact output:
[<Animal.ANT: 1>, <Animal.BEE: 2>, <Animal.CAT: 3>]
2
True
3
The result is a real enum class with the same lookups, listing, and identity rules as a class statement. The class statement stays the better default in source code, since the members read as code and tools can find them; the call form earns its place when the names themselves arrive as data.
The traps: ordering, unknown lookups, and zero
from enum import Enum
class Color(Enum):
RED = 1
GREEN = 2
try:
print(Color.RED < Color.GREEN)
except TypeError:
print("TypeError")
try:
print(Color(9))
except ValueError:
print("ValueError")
try:
print(Color["PURPLE"])
except KeyError:
print("KeyError")
class Switch(Enum):
OFF = 0
ON = 1
print(bool(Switch.OFF))
print(Switch.OFF.value == 0)
The exact output:
TypeError
ValueError
KeyError
True
True
The off member is a real member and reads as true, while its value compares equal to 0. Code that branches on whether a switch is off compares the member itself, state is Switch.OFF, and never tests the member for truth. The flag form in the section above is the exception: its empty combination is defined to read as false.
Which choice for which job
| Job | Choice | Why |
|---|---|---|
| Named choices only | Enum with auto |
Values stay an internal detail |
| Choices stored as text | StrEnum |
Member equals its text value |
| Codes that arrive as numbers | IntEnum |
Compares, sorts, and equals the number |
| Overlapping choices | IntFlag |
Combinations with the or operator |
| A repeated value is a bug | @unique |
Fails at class definition |
| Names held as data | Functional call | Builds the class from a list or mapping |
| Second spelling of one choice | Alias | Same member, no extra count |
Checklist
- Compare members with
isor==against the member, never against a bare number or text, except on the IntEnum andStrEnumforms that define that equality. - Give every distinct choice its own value; a repeated value makes an alias, not a member.
- Add
@uniquewhere a repeated value would be a mistake. - Test a flag combination with
infor one flag, and remember the empty combination reads as false. - Never test a plain member for truth to mean its value; a member with value 0 still reads as true.
- Catch ValueError on a value lookup and KeyError on a name lookup where outside data enters.
Related guides on this site
- Python dataclasses — Fields, Defaults, and Equality — the class form that often holds an enum member as one of its fields.
- Python sorting — sorted, sort, and key — ordering values in general, where this guide covers why plain members refuse to order.
- Python dictionaries, lists, and sets — the plain containers an enum replaces when the set of choices is fixed.
Sources
- Python Standard Library, enum — Enum,
auto, IntEnum, StrEnum, IntFlag, aliases,unique, and the functional call. - Python HOWTO, Enum — worked examples for members, flags, and lookups.
Keep Exploring
The full Python hub \u2014 language basics, the standard library, and data tools.
Every guide on the site in one list, grouped by topic.
Every browser-only checker and verifier on the site.
The C++, Python, Sysadmin, Rust, Go, and TypeScript hubs.