Install & Compatibility
Where this runs
tested against v2.11.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.915 runs
installs and imports cleanly · install 0.0s · import 0.188s · 28.5MB
glibcpy 3.10–3.915 runs
installs and imports cleanly · install 6.6s · import 0.170s · 28MB
70MB installed
● package 70MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Color
✓ from pydantic_extra_types.color import Color
✗ from pydantic import Color
The `Color` type was moved from the main Pydantic library to pydantic-extra-types in Pydantic V2.
PhoneNumber
✓ from pydantic_extra_types.phone_numbers import PhoneNumber
Requires the `phonenumbers` optional dependency.
CountryAlpha2
✓ from pydantic_extra_types.country import CountryAlpha2
Requires the `pycountry` optional dependency.
SemanticVersion
✓ from pydantic_extra_types.semantic_version import SemanticVersion
✗ from pydantic_extra_types.semver import SemanticVersion
The `semver` module was deprecated in `v2.10.0` in favor of `semantic_version`.
This example demonstrates defining a Pydantic model with a `PhoneNumber` field, which automatically validates the input. Note that `PhoneNumber` requires the `phonenumbers` optional dependency.
from pydantic import BaseModel, ValidationError
from pydantic_extra_types.phone_numbers import PhoneNumber
class Contact(BaseModel):
name: str
phone: PhoneNumber
try:
# Valid phone number
c = Contact(name='Alice', phone='+1 650-253-0000')
print(c.phone.e164) # Outputs: +16502530000 (formatted by default as RFC3966 or E164, depending on version/config)
# Invalid phone number
Contact(name='Bob', phone='not-a-phone-number')
except ValidationError as e:
print(f"Validation error: {e}")
Debug
Known issues
breakingWhen migrating from Pydantic V1 to V2, types like `Color` and `PaymentCardNumber` were moved out of the main `pydantic` library into `pydantic-extra-types`. Direct imports from `pydantic.color` or `pydantic.payment` will no longer work.fixUpdate your imports from `from pydantic import Color` to `from pydantic_extra_types.color import Color`, and ensure `pydantic-extra-types` is installed.
affects: Pydantic v2.0.0 and later.
deprecatedThe previous `semver` module, which relied on the external `python-semver` package, has been deprecated in `v2.10.0`. It was replaced by an internal `SemanticVersion` type.fixMigrate imports from `from pydantic_extra_types.semver import SemVer` (or similar) to `from pydantic_extra_types.semantic_version import SemanticVersion`.
affects: 2.10.0+
gotchaMany specialized types within `pydantic-extra-types` require additional optional dependencies to be installed. For example, `PhoneNumber` requires `phonenumbers`, `Country` types require `pycountry`, and `PendulumDuration` requires `pendulum`. Simply installing `pydantic-extra-types` without specifying extras will lead to `ModuleNotFoundError` when these types are used.fixInstall `pydantic-extra-types` with the necessary extras, e.g., `pip install "pydantic-extra-types[phonenumbers,pycountry]"` or `pip install "pydantic-extra-types[all]"`.
affects: All versions
gotchaMost types are not directly available from the top-level `pydantic_extra_types` package but are nested within submodules. For instance, `Color` is in `pydantic_extra_types.color`, and `PhoneNumber` is in `pydantic_extra_types.phone_numbers`. Attempting `from pydantic_extra_types import Color` will result in an `ImportError`.fixAlways import types from their specific submodules, e.g., `from pydantic_extra_types.color import Color`.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'pydantic_extra_types'
The `pydantic-extra-types` library has not been installed in your Python environment.
fixpip install pydantic-extra-types
ImportError: cannot import name 'Color' from 'pydantic.color'
In Pydantic V2, types like `Color` and `PaymentCardNumber` were moved from the main `pydantic` package to `pydantic-extra-types`.
fixUpdate your import statement from `from pydantic import Color` to `from pydantic_extra_types.color import Color` (or similar for other moved types).
PydanticCustomError: 'color_error', 'value is not a valid color: value must be a tuple, list or string'
The input value provided for a `pydantic-extra-types` field, such as `Color`, does not conform to its expected format or validation rules.
fixEnsure the input value matches the required format for the specific extra type (e.g., a valid color string like '#FFF' or 'red', or an RGB/RGBA tuple).
ModuleNotFoundError: No module named 'phonenumbers'
Specific types within `pydantic-extra-types`, such as `PhoneNumber` and `ULID`, have additional external dependencies (`phonenumbers` and `python-ulid` respectively) that must be installed separately.
fixInstall the missing optional dependency for the specific extra type you are using. For `PhoneNumber`, run `pip install phonenumbers`. For `ULID`, run `pip install python-ulid`.
Upgrade
Version history
2.11.1latest on PyPI · released Mar 16, 2026
Audit
Dependencies
pydanticrequiredCore data validation library that pydantic-extra-types extends.
phonenumbersoptionalRequired for the `PhoneNumber` type.
pendulumoptionalRequired for `PendulumDuration` type and related datetime functionalities.
pycountryoptionalRequired for `CountryAlpha2`, `CountryAlpha3`, and `CountryNumericCode` types.
python-ulidoptionalRequired for the `ULID` type.
pymongooptionalRequired for `MongoObjectId` type.
cron-converteroptionalRequired for the `Cron` type.
uuid-utilsoptionalRequired for `UUIDv6`, `UUIDv7`, and `UUIDv8` types.
pytzoptionalOptional dependency for timezone support with some types (or `tzdata`).
tzdataoptionalOptional dependency for timezone support with some types (or `pytz`).
semveroptionalRequired for older `semver` type (deprecated in favor of `SemanticVersion`).