Django Timezone Utilities

0.15.0 · active · verified Fri Apr 17

`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.

Common errors

```
AttributeError: type object 'TimeZoneField' has no attribute 'get_prep_value'
```
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).

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`.
```
ModuleNotFoundError: No module named 'timezone_utils'
```
cause The `django-timezone-utils` package is not installed or not available in your current Python environment.

fix Install the package using `pip install django-timezone-utils`.
```
ImportError: cannot import name 'TimeZoneField' from 'timezone_utils.models'
```
cause Prior to v0.11, `TimeZoneField` might have been importable from `timezone_utils.models`. This module path was removed in v0.11.

fix Change your import statement to `from timezone_utils.fields import TimeZoneField`.

Warnings

breaking 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.
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`.
gotcha 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.
Fix: Check the `django-timezone-utils` release notes or README for exact Django version compatibility and upgrade/downgrade your library version accordingly.
gotcha 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`.
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`.

Install

pip install django-timezone-utils Install latest version

Imports

TimeZoneField
wrong:
```
from timezone_utils.models import TimeZoneField
```
correct:
```
from timezone_utils.fields import TimeZoneField
```
The 'timezone_utils.models' path for TimeZoneField was removed in v0.11; it is now correctly found in 'timezone_utils.fields'.

TIMEZONE_CHOICES_STANDARD

from timezone_utils.choices import TIMEZONE_CHOICES_STANDARD

TIMEZONE_CHOICES_WITH_GMT_OFFSET

from timezone_utils.choices import TIMEZONE_CHOICES_WITH_GMT_OFFSET

Quickstart

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.

from django.db import models
from timezone_utils.fields import TimeZoneField

class Event(models.Model):
    name = models.CharField(max_length=100)
    # Use TimeZoneField to store a timezone string, e.g., 'America/New_York'
    # The 'choices_display' argument requires django-timezone-utils >= 0.15.0.
    # For older versions, pass 'choices=TIMEZONE_CHOICES_STANDARD' instead.
    timezone = TimeZoneField(
        default="America/New_York",
        choices_display="WITH_GMT_OFFSET" # Or "STANDARD"
    )

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

view raw JSON →