Django Timezone Field

7.2.1 · active · verified Thu Apr 09

django-timezone-field is an actively maintained Django app that provides database, form, and Django REST Framework fields for handling `zoneinfo` and `pytz` timezone objects. It is currently at version 7.2.1 (released December 2025) and regularly updates to support the latest Django and Python versions. Its primary function is to simplify the storage and manipulation of timezone data within Django applications, abstracting away the complexities of `pytz` and the newer `zoneinfo` module.

Warnings

breaking Breaking change in `django-timezone-field` 6.0: `pytz` was removed as a direct dependency. If your project relies on `use_pytz=True` (which is often the default for Django < 5.x), you must explicitly `pip install pytz` in your project's environment.
Fix: If `use_pytz=True` is in effect (either explicitly or implicitly by Django version), manually add `pytz` to your project's dependencies: `pip install pytz`.
breaking Breaking change in `django-timezone-field` 7.0: Assigning a string to a `TimeZoneField` now immediately converts it to a timezone object and raises a `ValidationError` if the string is not a recognized timezone. Previously, this conversion and validation might have been delayed until `full_clean` or `save`.
Fix: Ensure that any string values assigned to `TimeZoneField` are valid IANA timezone identifiers (e.g., 'America/New_York'). Validate user input earlier if necessary.
gotcha When using `zoneinfo` (default for Python 3.9+ and modern Django), `ZoneInfoNotFoundError` can occur if the local system's timezone database does not contain the requested timezone.
Fix: Install the `tzdata` package (`pip install tzdata`) to provide a comprehensive IANA timezone database for `zoneinfo` to reference.
gotcha Django 5.x and later have fully deprecated `pytz` in favor of `zoneinfo`. While `django-timezone-field` supports both, be aware of Django's native behavior.
Fix: Favor `zoneinfo`-based operations where possible, especially in new code. Ensure `tzdata` is installed if you encounter `ZoneInfoNotFoundError`.
gotcha Prior to `django-timezone-field` version 7.0, the default choices for the form field transitioned from `pytz.all_timezones` to `pytz.common_timezones` (in versions 1.1/1.2). If your application relies on timezones outside of `common_timezones`, you might encounter validation errors.
Fix: Explicitly define `choices` in your `TimeZoneField` definition, e.g., `choices=[(tz, tz) for tz in pytz.all_timezones]` to restore the broader set of timezones if needed.
gotcha Always use timezone-aware `datetime` objects (e.g., `django.utils.timezone.now()`) when `USE_TZ = True` in Django settings, rather than naive `datetime.datetime.now()`. Mixing aware and naive datetimes leads to `TypeError: can't compare offset-naive and offset-aware datetimes`.
Fix: Use `django.utils.timezone.now()` for current time and ensure all `datetime` objects interacting with Django's timezone-aware system are also aware. Convert naive datetimes to aware ones using `timezone.make_aware()`.

Install

pip install django-timezone-field Install stable version

Imports

TimeZoneField

from timezone_field.fields import TimeZoneField

TimeZoneSerializerField

from timezone_field.rest_framework import TimeZoneSerializerField

Quickstart

Define a Django model with a `TimeZoneField` to store timezone objects. The field handles validation and conversion between string representations in the database and `zoneinfo.ZoneInfo` (or `pytz` timezone) objects in Python. You can set a default timezone using a string or a timezone object.

from django.db import models
from timezone_field import TimeZoneField

# For ZoneInfo (Python 3.9+ / modern Django) or pytz (older Django)
# You might need 'tzdata' installed for ZoneInfo if your system's timezone DB is incomplete.

class Event(models.Model):
    name = models.CharField(max_length=255)
    # Default behavior (uses zoneinfo on Django >= 5.x, pytz on older)
    timezone = TimeZoneField(default="UTC")

    # Example with explicit pytz usage (requires pytz installed if on >= 6.0)
    # For Django < 5.x, this field would default to use_pytz=True implicitly.
    # from pytz import timezone
    # explicit_pytz_tz = TimeZoneField(use_pytz=True, default=timezone('America/New_York'))

    # Example with choices_display for forms
    # from timezone_field.choices import WITH_GMT_OFFSET
    # display_timezone = TimeZoneField(choices_display=WITH_GMT_OFFSET)

    def __str__(self):
        return f"{self.name} ({self.timezone})"

# Example usage:
# event = Event.objects.create(name="Meeting", timezone="America/Los_Angeles")
# print(event.timezone) # Returns a zoneinfo.ZoneInfo or pytz.timezone object

view raw JSON →