Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Using Python enum.auto() for Automatic Enum Values

Learn how Python's enum.auto() assigns values, how to customize the generation hook, and when explicit enum values are safer.

~4 min readPython
#Enum#auto()#Python#Code Generation
Illustration of Python enum members being assigned sequential values automatically by the auto() function

When you define an enum in Python, every member normally has an explicit value. For many enums, though, the exact value is an implementation detail; only the member names matter. Writing 1, 2, 3 by hand is noise and invites mistakes when you insert a member later. The auto() helper from the enum module generates those values for you:

python
from enum import Enum, auto class Color(Enum): RED = auto() GREEN = auto() BLUE = auto()

Each member gets a unique integer value in definition order: Color.RED.value is 1, Color.GREEN.value is 2, and so on. Use auto() when the numeric value carries no domain meaning.

How auto() Assigns Values

auto() delegates value generation to _generate_next_value_(). The enum machinery calls this hook once for each member that uses auto(), while the class is being defined. For a plain Enum, the default hook returns start for the first generated value and then continues from the previous member value; for numeric values this produces sequential integers starting at 1.

The hook receives four arguments:

  • name: the member name
  • start: the start value (defaults to 1)
  • count: the number of members already defined
  • last_values: the values of previously defined members, including explicit values

Because last_values includes explicit values, explicit values can affect the next auto() value. In the next example, PENDING is 0, so the first auto() member receives 1:

python
class Status(Enum): PENDING = 0 ACTIVE = auto() # 1 DISABLED = auto() # 2

If you need a different relationship between explicit and auto values, override the hook.

Using auto() with IntEnum and StrEnum

auto() works with any Enum subclass. IntEnum values remain integers, so they can be used in comparisons or as list indices. StrEnum, added in Python 3.11, uses strings; for auto() it uses the lowercased member name as the value.

python
from enum import IntEnum, StrEnum, auto class Priority(IntEnum): LOW = auto() # 1 MEDIUM = auto() # 2 HIGH = auto() # 3 class Direction(StrEnum): NORTH = auto() # 'north' SOUTH = auto() # 'south'

The mechanism is the same: _generate_next_value_() is called for each auto() member and can be overridden in these subclasses too.

Customizing Value Generation

If the default values do not fit, override _generate_next_value_() in your enum class. It receives the name, start, count, and last_values arguments described above.

A common customization is to use a different step:

python
class Port(Enum): def _generate_next_value_(name, start, count, last_values): return start + count * 2 HTTP = auto() # 1 HTTPS = auto() # 3 FTP = auto() # 5

Here start defaults to 1, and count increases once per member, so the values become 1, 3, 5. You can also use last_values to base values on the previous member, which is useful when you mix explicit and auto values:

python
class Offset(Enum): def _generate_next_value_(name, start, count, last_values): return last_values[-1] + 10 if last_values else start FIRST = 100 SECOND = auto() # 110 THIRD = auto() # 120

The override applies to every auto() call in that enum.

Mixing Explicit Values and auto()

You can mix explicit values and auto(), but know how the default hook behaves. With a plain numeric Enum, the default continues from the last defined value, whether that value was explicit or auto-generated:

python
class Example(Enum): A = auto() # 1 B = 10 C = auto() # 11

This is usually the least surprising behavior. If you need auto() to use an independent counter instead of following the previous value, or if you need a different increment, override _generate_next_value_().

Runtime Cost and Maintainability

auto() is evaluated at class definition time, not when members are accessed. The generated values are stored like any other enum value, so there is no per-access overhead. The only work is the one-time call to _generate_next_value_() for each auto() member.

For maintainability, auto() removes duplication and makes insertion less error-prone. Adding a member in the middle of an explicit sequential enum forces you to renumber everything after it; with auto() the values adjust automatically. If the values are part of a stable public API, however, explicit values are safer, because they do not change when members are reordered or removed. auto() is best for internal enums where the exact value is irrelevant.

Compatibility and Version Considerations

auto() is available from Python 3.6. StrEnum requires Python 3.11. Because _generate_next_value_() is a hook, the generated numbers depend on the implementation in the Python version you use. If a specific numeric pattern matters, verify it in your target runtime or override the hook to make the behavior explicit.

Overriding the Start Value

The functional API accepts a start argument that changes the first value used for generated members:

python
ErrorCode = Enum('ErrorCode', ['A', 'B', 'C'], start=1000) list(ErrorCode) # [<ErrorCode.A: 1000>, <ErrorCode.B: 1001>, <ErrorCode.C: 1002>]

For class syntax, there is no dedicated start= argument. Use the functional API, or override _generate_next_value_() to change where numbering begins.

When Not to Use auto()

auto() is not suitable when the value itself is part of the contract. For HTTP status codes, persisted enum values, or wire protocol constants, explicit values make the contract visible and prevent accidental changes. Use auto() only when the value is an implementation detail and the member name is the primary identity.

For bit flags, use enum.Flag rather than a plain Enum; auto() in a Flag subclass generates powers of two:

python
from enum import Flag, auto class Permission(Flag): READ = auto() WRITE = auto() EXECUTE = auto()

Here the values are 1, 2, and 4. With a plain Enum, bit-mask values should be explicit.

Try matching browser tools

All tools

Small utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Python guides

More in Python

All Python guides

The guides filed next to this one in Python, in library order.