django-timezone-field

django-timezone-field is a small Django app that provides a TimeZoneField model field, plus matching form and Django REST Framework serializer fields, for storing and validating IANA timezone values directly on your models. Rather than storing a timezone as a plain string and validating it ad hoc, this field stores a real timezone object and integrates cleanly with Django’s forms, admin, and serialization layers.

The library tracks Django’s own transition from pytz to the standard-library zoneinfo module, supporting both timezone object types via a use_pytz flag that defaults to match Django’s own version-dependent default behavior, so projects can migrate at their own pace without breaking existing data.

What You Get

• A TimeZoneField Django model field with configurable choices, validation, and default timezone
• A matching Django form field for validating timezone input in forms and the admin
• A Django REST Framework serializer field for validating/serializing timezones in APIs
• Dual support for pytz and zoneinfo timezone objects via a use_pytz flag, tracking Django’s own migration path
• Sensible defaults for use_pytz that automatically match the installed Django version’s own default behavior
• A restricted-choices option to limit the field to a specific subset of timezones (e.g. only US zones)

Common Use Cases

• Storing a user’s preferred timezone on a Django User profile model for correctly localized datetime display
• Validating timezone input from a signup or settings form without writing custom validation logic
• Exposing a timezone field on a Django REST Framework API serializer with built-in validation
• Migrating a Django project from pytz to zoneinfo incrementally while both are supported

Under The Hood

Architecture - The package is organized around a single TimeZoneField implementation in timezone_field/ that subclasses Django’s model field API (get_prep_value, to_python, formfield) to handle serialization to/from a plain string column, with parallel form-field and DRF serializer-field classes reusing the same core validation logic against the pytz/zoneinfo timezone name lists.

Tech Stack - Pure Python, packaged with Poetry (pyproject.toml/poetry.lock), depending on Django itself plus optionally pytz and Django REST Framework; no compiled extensions or non-Python dependencies.

Code Quality - The tests/ directory (8 test files) covers model field behavior, form validation, and the pytz/zoneinfo compatibility layer across supported Django versions, with CI running via GitHub Actions and coverage tracked through Codecov; the project has been maintained since 2012 with a large contributor base (29 contributors) but currently sees infrequent (moderate-activity) maintenance, consistent with a small, feature-complete utility library rather than one under active expansion.

API Design - The field classes follow Django’s own field-subclassing conventions exactly, so adoption is a drop-in models.TimeZoneField() declaration familiar to anyone who has used Django’s built-in field types; the use_pytz compatibility flag adds a small amount of conceptual overhead but is well-documented and defaults sensibly per Django version.