{"id":1460,"library":"django-timezone-field","title":"Django Timezone Field","description":"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.","status":"active","version":"7.2.1","language":"en","source_language":"en","source_url":"https://github.com/mfogel/django-timezone-field/","tags":["django","timezone","field","pytz","zoneinfo","database","forms","rest-framework","i18n"],"install":[{"cmd":"pip install django-timezone-field","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core dependency for a Django application, compatible with Django >=3.8.","package":"Django","optional":false},{"reason":"Required if `use_pytz=True` is explicitly set (e.g., for compatibility with Django < 5.x). As of `django-timezone-field` 6.0, `pytz` is no longer a direct dependency and must be installed separately if needed.","package":"pytz","optional":true},{"reason":"Recommended for full IANA timezone database coverage when using `zoneinfo` (default for Python 3.9+ and modern Django) to prevent `ZoneInfoNotFoundError` if the local system's timezone database is incomplete.","package":"tzdata","optional":true},{"reason":"Required for `TimeZoneSerializerField` to integrate with Django REST Framework.","package":"djangorestframework","optional":true}],"imports":[{"symbol":"TimeZoneField","correct":"from timezone_field.fields import TimeZoneField"},{"symbol":"TimeZoneSerializerField","correct":"from timezone_field.rest_framework import TimeZoneSerializerField"}],"quickstart":{"code":"from django.db import models\nfrom timezone_field import TimeZoneField\n\n# For ZoneInfo (Python 3.9+ / modern Django) or pytz (older Django)\n# You might need 'tzdata' installed for ZoneInfo if your system's timezone DB is incomplete.\n\nclass Event(models.Model):\n    name = models.CharField(max_length=255)\n    # Default behavior (uses zoneinfo on Django >= 5.x, pytz on older)\n    timezone = TimeZoneField(default=\"UTC\")\n\n    # Example with explicit pytz usage (requires pytz installed if on >= 6.0)\n    # For Django < 5.x, this field would default to use_pytz=True implicitly.\n    # from pytz import timezone\n    # explicit_pytz_tz = TimeZoneField(use_pytz=True, default=timezone('America/New_York'))\n\n    # Example with choices_display for forms\n    # from timezone_field.choices import WITH_GMT_OFFSET\n    # display_timezone = TimeZoneField(choices_display=WITH_GMT_OFFSET)\n\n    def __str__(self):\n        return f\"{self.name} ({self.timezone})\"\n\n# Example usage:\n# event = Event.objects.create(name=\"Meeting\", timezone=\"America/Los_Angeles\")\n# print(event.timezone) # Returns a zoneinfo.ZoneInfo or pytz.timezone object","lang":"python","description":"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."},"warnings":[{"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`.","message":"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.","severity":"breaking","affected_versions":">=6.0"},{"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.","message":"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`.","severity":"breaking","affected_versions":">=7.0"},{"fix":"Install the `tzdata` package (`pip install tzdata`) to provide a comprehensive IANA timezone database for `zoneinfo` to reference.","message":"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.","severity":"gotcha","affected_versions":"All versions using `zoneinfo` backend."},{"fix":"Favor `zoneinfo`-based operations where possible, especially in new code. Ensure `tzdata` is installed if you encounter `ZoneInfoNotFoundError`.","message":"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.","severity":"gotcha","affected_versions":">=6.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<7.0 (specifically from 1.1/1.2)"},{"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()`.","message":"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`.","severity":"gotcha","affected_versions":"All versions of Django with `USE_TZ=True`"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}