Install & Compatibility
Where this runs
tested against v7.2.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 66.4MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.5s · import 0.000s · 67MB
66MB installed
● package 66MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
TimeZoneField
✓ from timezone_field import TimeZoneField
✗ from timezone_field import TimeZoneField
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
Debug
Known issues
breakingBreaking 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.fixIf `use_pytz=True` is in effect (either explicitly or implicitly by Django version), manually add `pytz` to your project's dependencies: `pip install pytz`.
affects: >=6.0
breakingBreaking 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`.fixEnsure that any string values assigned to `TimeZoneField` are valid IANA timezone identifiers (e.g., 'America/New_York'). Validate user input earlier if necessary.
affects: >=7.0
gotchaWhen 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.fixInstall the `tzdata` package (`pip install tzdata`) to provide a comprehensive IANA timezone database for `zoneinfo` to reference.
affects: All versions using `zoneinfo` backend.
gotchaDjango 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.fixFavor `zoneinfo`-based operations where possible, especially in new code. Ensure `tzdata` is installed if you encounter `ZoneInfoNotFoundError`.
affects: >=6.0
gotchaPrior 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.fixExplicitly 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.
affects: <7.0 (specifically from 1.1/1.2)
gotchaAlways 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`.fixUse `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()`.
affects: All versions of Django with `USE_TZ=True`
gotchaImporting `django-timezone-field` components (e.g., `TimeZoneField`) in an environment where Django settings are not configured will raise `django.core.exceptions.ImproperlyConfigured`. This is because the library accesses `Django.conf.settings` during its initialization.fixEnsure Django settings are configured before importing `django-timezone-field`. This can be achieved by either setting the `DJANGO_SETTINGS_MODULE` environment variable to your project's settings file or by explicitly calling `django.conf.settings.configure()` in your script (e.g., `from django.conf import settings; settings.configure(USE_DEPRECATED_PYTZ=False)` for a minimal setup).
affects: All versions
gotchaImporting `django-timezone-field` components requires Django settings to be configured. If Django settings are not set up (e.g., in a standalone script or test environment without `DJANGO_SETTINGS_MODULE` environment variable or an explicit `settings.configure()` call), a `django.core.exceptions.ImproperlyConfigured` error will occur when the library attempts to access `django.conf.settings` during import.fixBefore importing `django-timezone-field` components, ensure Django settings are configured. This can be done by setting the `DJANGO_SETTINGS_MODULE` environment variable to your project's settings file (e.g., `export DJANGO_SETTINGS_MODULE='your_project.settings'`) or by explicitly calling `django.conf.settings.configure()` in your script/test setup (e.g., `from django.conf import settings; settings.configure(...)`).
affects: All versions (where Django settings are accessed during import)
Upgrade
Version history
7.2.2latest on PyPI · released Jun 6, 2026
Audit
Dependencies
DjangorequiredCore dependency for a Django application, compatible with Django >=3.8.
pytzoptionalRequired 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.
tzdataoptionalRecommended 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.
djangorestframeworkoptionalRequired for `TimeZoneSerializerField` to integrate with Django REST Framework.