{"id":9688,"library":"django-timezone-utils","title":"Django Timezone Utilities","description":"`django-timezone-utils` provides a `TimeZoneField` for Django models, allowing storage and management of timezone information as strings (e.g., 'America/New_York'). It includes choices for displaying timezones and integrates seamlessly with Django's ORM and forms. The current version, 0.15.0, supports Django 4.x and Python 3, with releases typically aligning with new Django major versions.","status":"active","version":"0.15.0","language":"en","source_language":"en","source_url":"https://github.com/michaeljohnbarr/django-timezone-utils/","tags":["django","timezone","models","fields","orm"],"install":[{"cmd":"pip install django-timezone-utils","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"This is a Django plugin and requires a compatible Django installation.","package":"Django","optional":false}],"imports":[{"note":"The 'timezone_utils.models' path for TimeZoneField was removed in v0.11; it is now correctly found in 'timezone_utils.fields'.","wrong":"from timezone_utils.models import TimeZoneField","symbol":"TimeZoneField","correct":"from timezone_utils.fields import TimeZoneField"},{"symbol":"TIMEZONE_CHOICES_STANDARD","correct":"from timezone_utils.choices import TIMEZONE_CHOICES_STANDARD"},{"symbol":"TIMEZONE_CHOICES_WITH_GMT_OFFSET","correct":"from timezone_utils.choices import TIMEZONE_CHOICES_WITH_GMT_OFFSET"}],"quickstart":{"code":"from django.db import models\nfrom timezone_utils.fields import TimeZoneField\n\nclass Event(models.Model):\n    name = models.CharField(max_length=100)\n    # Use TimeZoneField to store a timezone string, e.g., 'America/New_York'\n    # The 'choices_display' argument requires django-timezone-utils >= 0.15.0.\n    # For older versions, pass 'choices=TIMEZONE_CHOICES_STANDARD' instead.\n    timezone = TimeZoneField(\n        default=\"America/New_York\",\n        choices_display=\"WITH_GMT_OFFSET\" # Or \"STANDARD\"\n    )\n\n    def __str__(self):\n        return f\"{self.name} in {self.timezone}\"","lang":"python","description":"Define a Django model with a `TimeZoneField` to store timezone information. The `choices_display` argument (available from v0.15.0) simplifies how timezone choices are presented in forms."},"warnings":[{"fix":"If upgrading from very old versions, consult the v0.11 release notes carefully. Update Django/Python, adjust imports (`TimeZoneField` is now from `timezone_utils.fields`), and remove any reliance on `SubfieldBase`.","message":"Significant breaking changes occurred in version 0.11: support for Django < 1.8 and Python < 2.6 was dropped. The internal `SubfieldBase` mechanism was removed, and modules like `timezone_utils/models.py` and `timezone_utils/migrations` were removed.","severity":"breaking","affected_versions":"< 0.11"},{"fix":"Check the `django-timezone-utils` release notes or README for exact Django version compatibility and upgrade/downgrade your library version accordingly.","message":"Always ensure `django-timezone-utils` is compatible with your Django version. Version 0.15.0 specifically targets Django 4.x, while 0.12 supported Django 2.1. Using an incompatible version may lead to unexpected errors or silent failures.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade to `django-timezone-utils >= 0.15.0` to use `choices_display`. Alternatively, for older versions, you can manually pass `choices=TIMEZONE_CHOICES_STANDARD` or `choices=TIMEZONE_CHOICES_WITH_GMT_OFFSET`.","message":"The `choices_display` argument for `TimeZoneField` was introduced in version 0.15.0. If you use it with an older package version, it will raise a `TypeError`.","severity":"gotcha","affected_versions":"< 0.15.0"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Ensure `django-timezone-utils` is `0.11` or newer and compatible with your Django version. If you have custom fields, recheck their implementation against Django's latest field API without `SubfieldBase`.","cause":"This error often indicates an incompatibility between your Django version and `django-timezone-utils`, or a custom field inheriting `TimeZoneField` that isn't updated for modern Django field APIs (e.g., related to `SubfieldBase` removal).","error":"AttributeError: type object 'TimeZoneField' has no attribute 'get_prep_value'"},{"fix":"Install the package using `pip install django-timezone-utils`.","cause":"The `django-timezone-utils` package is not installed or not available in your current Python environment.","error":"ModuleNotFoundError: No module named 'timezone_utils'"},{"fix":"Change your import statement to `from timezone_utils.fields import TimeZoneField`.","cause":"Prior to v0.11, `TimeZoneField` might have been importable from `timezone_utils.models`. This module path was removed in v0.11.","error":"ImportError: cannot import name 'TimeZoneField' from 'timezone_utils.models'"}]}