Pydantic · Pipe

use_enum_values

use_enum_values=True makes Pydantic populate enum fields with their underlying values rather than enum members. Optional enum defaults need validate_default=True for this conversion to apply.

How it works

Set use_enum_values=True in ConfigDict to make validated enum fields hold their underlying values instead of enum members. For an optional enum default, add validate_default=True to its Field, because conversion happens during validation.

Syntax

ConfigDict(use_enum_values=True)

Returns

The setting changes populated field values; the documented example shows model_dump() containing underlying enum values.

Key points

When enabled, enum-typed fields are populated with each member's underlying value instead of the enum object.
The option is useful when a later model_dump() should contain serialization-friendly enum values.
The setting is disabled by default; enable it explicitly in the model configuration.
Enum value extraction happens during validation, not when the model is serialized.
The documented example shows model_dump() returning strings such as 'bar' and 'foo' after the option is enabled.

Common mistakes

An optional enum field with a default needs validate_default=True; otherwise its default is not converted.

Example: Store enum values

from enum import Enum
from typing import Optional
from pydantic import BaseModel, ConfigDict, Field

class Flavor(Enum):
    VANILLA = "vanilla"
    CHOCOLATE = "chocolate"

class Order(BaseModel):
    model_config = ConfigDict(use_enum_values=True)
    flavor: Flavor
    fallback: Optional[Flavor] = Field(
        default=Flavor.VANILLA, validate_default=True
    )

order = Order(flavor=Flavor.CHOCOLATE)
assert order.model_dump() == {"flavor": "chocolate", "fallback": "vanilla"}
print(order.model_dump())

The model stores enum values and validates the optional default so it is converted as well.

When to use it

Value-oriented output

Models whose dumped data is sent to JSON APIs or persistence layers.

Consistent defaults

Schemas containing optional enum fields with defaults.

Simpler downstream processing

Applications that compare or transform dumped data using primitive values.

Interview questions

QHow do you configure a Pydantic model to use enum values?

Set model_config = ConfigDict(use_enum_values=True) on the model. Enum inputs are then populated using each enum member's value, which is also convenient when calling model_dump().

Follow-up: Why might an optional enum default remain an enum member? Because defaults are not validated automatically in this case; enable validate_default=True on the field.

QWhat is the default behavior of use_enum_values?

The setting defaults to False, so the model otherwise retains raw enum members. With it enabled, a member such as SomeEnum.BAR is represented by its underlying value, such as 'bar'.

Follow-up: Where does the conversion occur? During validation, rather than during serialization, which explains the need to validate relevant defaults.

QHow should optional enum defaults be handled?

Add Field(default=..., validate_default=True) to an optional enum field that has a default. This causes the default to pass through validation and receive the same value extraction as supplied input.

Follow-up: What output should be expected from model_dump() after enabling the option? Enum fields appear as their underlying values, including validated defaults.

ConfigDict
Field
validate_default
BaseModel.model_dump
Enum

Source: Configuration - Pydantic. Checked 2026-10-15.