Python

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

By the end of this guide
  • 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:

Python
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:

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:

Python
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:

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:

Python
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:

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:

Python
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:

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:

Python
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:

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:

Python
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:

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

Trap
Three traps recur. A plain Enum has no ordering, so a comparison between members raises TypeError. A lookup with an unknown value raises ValueError, and a lookup with an unknown name raises KeyError; both fail at the lookup, which running code can catch and report. The third trap is quieter: a member is always true in a truth test, even when its value is 0, so a test on the member and a test on its value answer differently:
Python
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:

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 is or == against the member, never against a bare number or text, except on the IntEnum and StrEnum forms that define that equality.
  • Give every distinct choice its own value; a repeated value makes an alias, not a member.
  • Add @unique where a repeated value would be a mistake.
  • Test a flag combination with in for 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.

Sources

Keep Exploring