Skip to main content

A Django app providing database and form fields for pytz timezone objects.

Project description


CI codecov pypi downloads pypi python support pypi django support

A Django app providing database, form and serializer fields for pytz timezone objects.


Database Field

import pytz
from django.db import models
from timezone_field import TimeZoneField

class MyModel(models.Model):
    tz1 = TimeZoneField(default='Europe/London')            # defaults supported
    tz2 = TimeZoneField()                                   # in ModelForm displays like "America/Los Angeles"
    tz3 = TimeZoneField(choices_display='WITH_GMT_OFFSET')  # in ModelForm displays like "GMT-08:00 America/Los Angeles"

my_model = MyModel(
    tz1='America/Los_Angeles',    # assignment of a string
    tz2=pytz.timezone('Turkey'),  # assignment of a pytz.DstTzInfo
    tz3=pytz.UTC,                 # assignment of pytz.UTC singleton
my_model.full_clean() # validates against pytz.common_timezones by default       # values stored in DB as strings
my_model.tz1          # values retrieved as pytz objects: <DstTzInfo 'America/Los_Angeles' PST-1 day, 16:00:00 STD>

Form Field

from django import forms
from timezone_field import TimeZoneFormField

class MyForm(forms.Form):
    tz = TimeZoneFormField()                                    # displays like "America/Los Angeles"
    tz2 = TimeZoneFormField(choices_display='WITH_GMT_OFFSET')  # displays like "GMT-08:00 America/Los Angeles"

my_form = MyForm({'tz': 'America/Los_Angeles'})
my_form.full_clean()        # validates against pytz.common_timezones by default
my_form.cleaned_data['tz']  # values retrieved as pytz objects: <DstTzInfo 'America/Los_Angeles' PST-1 day, 16:00:00 STD>

REST Framework Serializer Field

import pytz
from rest_framework import serializers
from timezone_field.rest_framework import TimeZoneSerializerField

class MySerializer(serializers.Serializer):
    tz1 = TimeZoneSerializerField()
    tz2 = TimeZoneSerializerField()

my_serializer = MySerializer(data={
    'tz1': 'America/Argentina/Buenos_Aires',
    'tz2': pytz.timezone('America/Argentina/Buenos_Aires'),
my_serializer.is_valid()            # true
my_serializer.validated_data['tz1'] # <DstTzInfo 'America/Argentina/Buenos_Aires' LMT-1 day, 20:06:00 STD>
my_serializer.validated_data['tz2'] # <DstTzInfo 'America/Argentina/Buenos_Aires' LMT-1 day, 20:06:00 STD>


  1. Install from pypi

    pip install django-timezone-field
  2. Add timezone_field to your django project's settings.INSTALLED_APPS

    INSTALLED_APPS = [..., 'timezone_field', ...]

Running the tests

From the repository root, with poetry

poetry install
poetry run pytest


4.2.1 (2021-07-07)

  • Reinstate TimeZoneField.default_choices (#76)

4.2 (2021-07-07)

  • Officially support for django 3.2, python 3.9
  • Fix bug with field deconstruction (#74)
  • Housekeeping: use poetry, github actions, pytest

4.1.2 (2021-03-17)

  • Avoid NonExistentTimeError during DST transition (#70)

4.1.1 (2020-11-28)

  • Don't import rest_framework from package root (#67)

4.1 (2020-11-28)

  • Add Django REST Framework serializer field
  • Add new choices_display kwarg with supported values WITH_GMT_OFFSET and STANDARD
  • Deprecate display_GMT_offset kwarg

4.0 (2019-12-03)

  • Add support for django 3.0, python 3.8
  • Drop support for django 1.11, 2.0, 2.1, python 2.7, 3.4

3.1 (2019-10-02)

  • Officially support django 2.2 (already worked)
  • Add option to display TZ offsets in form field (#46)

3.0 (2018-09-15)

  • Support django 1.11, 2.0, 2.1
  • Add support for python 3.7
  • Change default human-readable timezone names to exclude underscores (#32 & #37)

2.1 (2018-03-01)

  • Add support for django 1.10, 1.11
  • Add support for python 3.6
  • Add wheel support
  • Support bytes in DB fields (#38 & #39)

2.0 (2016-01-31)

  • Drop support for django 1.7, add support for django 1.9
  • Drop support for python 3.2, 3.3, add support for python 3.5
  • Remove tests from source distribution

1.3 (2015-10-12)

  • Drop support for django 1.6, add support for django 1.8
  • Various bug fixes

1.2 (2015-02-05)

  • For form field, changed default list of accepted timezones from pytz.all_timezones to pytz.common_timezones, to match DB field behavior.

1.1 (2014-10-05)

  • Django 1.7 compatibility
  • Added support for formatting choices kwarg as [[<str>, <str>], ...], in addition to previous format of [[<pytz.timezone>, <str>], ...].
  • Changed default list of accepted timezones from pytz.all_timezones to pytz.common_timezones. If you have timezones in your DB that are in pytz.all_timezones but not in pytz.common_timezones, this is a backward-incompatible change. Old behavior can be restored by specifying choices=[(tz, tz) for tz in pytz.all_timezones] in your model definition.

1.0 (2013-08-04)

  • Initial release as timezone_field.


Originally adapted from Brian Rosner's django-timezones.

Made possible thanks to the work of the contributors.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for django-timezone-field, version 4.2.1
Filename, size File type Python version Upload date Hashes
Filename, size django_timezone_field-4.2.1-py3-none-any.whl (9.7 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size django-timezone-field-4.2.1.tar.gz (8.9 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page