When support for time zones is enabled, Django stores datetime information in\nUTC in the database, uses time-zone-aware datetime objects internally, and\nconverts them to the end user’s time zone in forms. Templates will use the\ndefault time zone, but this can be updated\nto the end user’s time zone through the use of filters and tags.
\nThis is handy if your users live in more than one time zone and you want to\ndisplay datetime information according to each user’s wall clock.
\nEven if your website is available in only one time zone, it’s still good\npractice to store data in UTC in your database. The main reason is daylight\nsaving time (DST). Many countries have a system of DST, where clocks are moved\nforward in spring and backward in autumn. If you’re working in local time,\nyou’re likely to encounter errors twice a year, when the transitions happen.\nThis probably doesn’t matter for your blog, but it’s a problem if you over bill\nor under bill your customers by one hour, twice a year, every year. The\nsolution to this problem is to use UTC in the code and use local time only when\ninteracting with end users.
\nTime zone support is enabled by default. To disable it, set USE_TZ =\nFalse in your settings file.
Time zone support uses zoneinfo, which is part of the Python standard\nlibrary from Python 3.9.
If you’re wrestling with a particular problem, start with the time zone\nFAQ.
\nPython’s datetime.datetime objects have a tzinfo attribute that\ncan be used to store time zone information, represented as an instance of a\nsubclass of datetime.tzinfo. When this attribute is set and describes\nan offset, a datetime object is aware. Otherwise, it’s naive.
You can use is_aware() and\nis_naive() to determine whether datetimes are\naware or naive.
When time zone support is disabled, Django uses naive datetime objects in local\ntime. This is sufficient for many use cases. In this mode, to obtain the\ncurrent time, you would write:
\nimport datetime\n\nnow = datetime.datetime.now()\nWhen time zone support is enabled (USE_TZ=True), Django\nuses time-zone-aware datetime objects. If your code creates datetime objects,\nthey should be aware too. In this mode, the example above becomes:
from django.utils import timezone\n\nnow = timezone.now()\nWhen USE_TZ is True, Django still accepts naive datetime\nobjects, in order to preserve backwards-compatibility. When the database layer\nreceives one, it attempts to make it aware by interpreting it in the\ndefault time zone and raises a warning.
Unfortunately, during DST transitions, some datetimes don’t exist or are\nambiguous. That’s why you should always create aware datetime objects when time\nzone support is enabled. (See the Using ZoneInfo section of the zoneinfo\ndocs for examples using the fold attribute to specify the\noffset that should apply to a datetime during a DST transition.)
In practice, this is rarely an issue. Django gives you aware datetime objects\nin the models and forms, and most often, new datetime objects are created from\nexisting ones through timedelta arithmetic. The only\ndatetime that’s often created in application code is the current time, and\ntimezone.now() automatically does the\nright thing.
The default time zone is the time zone defined by the TIME_ZONE\nsetting.
The current time zone is the time zone that’s used for rendering.
\nYou should set the current time zone to the end user’s actual time zone with\nactivate(). Otherwise, the default time zone is\nused.
The current time zone is the equivalent of the current locale for translations. However, there’s no equivalent of the\nAccept-Language HTTP header that Django could use to determine the user’s\ntime zone automatically. Instead, Django provides time zone selection\nfunctions. Use them to build the time zone\nselection logic that makes sense for you.
Most websites that care about time zones ask users in which time zone they live\nand store this information in the user’s profile. For anonymous users, they use\nthe time zone of their primary audience or UTC.\nzoneinfo.available_timezones() provides a set of available timezones that\nyou can use to build a map from likely locations to time zones.
Here’s an example that stores the current timezone in the session. (It skips\nerror handling entirely for the sake of simplicity.)
\nAdd the following middleware to MIDDLEWARE:
import zoneinfo\n\nfrom django.utils import timezone\n\n\nclass TimezoneMiddleware:\n def __init__(self, get_response):\n self.get_response = get_response\n\n def __call__(self, request):\n tzname = request.session.get("django_timezone")\n if tzname:\n timezone.activate(zoneinfo.ZoneInfo(tzname))\n else:\n timezone.deactivate()\n return self.get_response(request)\nCreate a view that can set the current timezone:
\nfrom django.shortcuts import redirect, render\n\n# Prepare a map of common locations to timezone choices you wish to offer.\ncommon_timezones = {\n "London": "Europe/London",\n "Paris": "Europe/Paris",\n "New York": "America/New_York",\n}\n\n\ndef set_timezone(request):\n if request.method == "POST":\n request.session["django_timezone"] = request.POST["timezone"]\n return redirect("/")\n else:\n return render(request, "template.html", {"timezones": common_timezones})\nInclude a form in template.html that will POST to this view:
{% load tz %}\n{% get_current_timezone as TIME_ZONE %}\n<form action="{% url 'set_timezone' %}" method="POST">\n {% csrf_token %}\n <label for="timezone">Time zone:</label>\n <select name="timezone">\n {% for city, tz in timezones.items %}\n <option value="{{ tz }}"{% if tz == TIME_ZONE %} selected{% endif %}>{{ city }}</option>\n {% endfor %}\n </select>\n <input type="submit" value="Set">\n</form>\nWhen you enable time zone support, Django interprets datetimes entered in\nforms in the current time zone and returns\naware datetime objects in cleaned_data.
Converted datetimes that don’t exist or are ambiguous because they fall in a\nDST transition will be reported as invalid values.
\nWhen you enable time zone support, Django converts aware datetime objects to\nthe current time zone when they’re rendered\nin templates. This behaves very much like format localization.
\n\nConversion to local time isn’t always appropriate – you may be generating\noutput for computers rather than for humans. The following filters and tags,\nprovided by the tz template tag library, allow you to control the time zone\nconversions.
These filters accept both aware and naive datetimes. For conversion purposes,\nthey assume that naive datetimes are in the default time zone. They always\nreturn aware datetimes.
\nlocaltimeLink to this heading#Forces conversion of a single value to the current time zone.
\nFor example:
\n{% load tz %}\n\n{{ value|localtime }}\nutcLink to this heading#Forces conversion of a single value to UTC.
\nFor example:
\n{% load tz %}\n\n{{ value|utc }}\ntimezoneLink to this heading#Forces conversion of a single value to an arbitrary timezone.
\nThe argument must be an instance of a tzinfo subclass or a\ntime zone name.
For example:
\n{% load tz %}\n\n{{ value|timezone:"Europe/Paris" }}\nHere’s how to migrate a project that was started before Django supported time\nzones.
\nThe PostgreSQL backend stores datetimes as timestamp with time zone. In\npractice, this means it converts datetimes from the connection’s time zone to\nUTC on storage, and from UTC to the connection’s time zone on retrieval.
As a consequence, if you’re using PostgreSQL, you can switch between USE_TZ\n= False and USE_TZ = True freely. The database connection’s time zone\nwill be set to DATABASE-TIME_ZONE or UTC respectively, so that\nDjango obtains correct datetimes in all cases. You don’t need to perform any\ndata conversions.
Other backends store datetimes without time zone information. If you switch\nfrom USE_TZ = False to USE_TZ = True, you must convert your data from\nlocal time to UTC – which isn’t deterministic if your local time has DST.
The first step is to add USE_TZ = True to your settings\nfile. At this point, things should mostly work. If you create naive datetime\nobjects in your code, Django makes them aware when necessary.
However, these conversions may fail around DST transitions, which means you\naren’t getting the full benefits of time zone support yet. Also, you’re likely\nto run into a few problems because it’s impossible to compare a naive datetime\nwith an aware datetime. Since Django now gives you aware datetimes, you’ll get\nexceptions wherever you compare a datetime that comes from a model or a form\nwith a naive datetime that you’ve created in your code.
\nSo the second step is to refactor your code wherever you instantiate datetime\nobjects to make them aware. This can be done incrementally.\ndjango.utils.timezone defines some handy helpers for compatibility\ncode: now(),\nis_aware(),\nis_naive(),\nmake_aware(), and\nmake_naive().
Finally, in order to help you locate code that needs upgrading, Django raises\na warning when you attempt to save a naive datetime to the database:
\nRuntimeWarning: DateTimeField ModelName.field_name received a naive\ndatetime (2012-01-01 00:00:00) while time zone support is active.\nDuring development, you can turn such warnings into exceptions and get a\ntraceback by adding the following to your settings file:
\nimport warnings\n\nwarnings.filterwarnings(\n "error",\n r"DateTimeField .* received a naive datetime",\n RuntimeWarning,\n r"django\\.db\\.models\\.fields",\n)\nWhen serializing an aware datetime, the UTC offset is included, like this:
\n"2011-09-01T13:20:30+03:00"\nWhile for a naive datetime, it isn’t:
\n"2011-09-01T13:20:30"\nFor models with DateTimeFields, this difference\nmakes it impossible to write a fixture that works both with and without time\nzone support.
Fixtures generated with USE_TZ = False, or before Django 1.4, use the\n“naive” format. If your project contains such fixtures, after you enable time\nzone support, you’ll see RuntimeWarnings when you load them. To get\nrid of the warnings, you must convert your fixtures to the “aware” format.
You can regenerate fixtures with loaddata then dumpdata.\nOr, if they’re small enough, you can edit them to add the UTC offset that\nmatches your TIME_ZONE to each serialized datetime.
I don’t need multiple time zones. Should I enable time zone support?
\nYes. When time zone support is enabled, Django uses a more accurate model\nof local time. This shields you from subtle and unreproducible bugs around\ndaylight saving time (DST) transitions.
\nWhen you enable time zone support, you’ll encounter some errors because\nyou’re using naive datetimes where Django expects aware datetimes. Such\nerrors show up when running tests. You’ll quickly learn how to avoid invalid\noperations.
\nOn the other hand, bugs caused by the lack of time zone support are much\nharder to prevent, diagnose and fix. Anything that involves scheduled tasks\nor datetime arithmetic is a candidate for subtle bugs that will bite you\nonly once or twice a year.
\nFor these reasons, time zone support is enabled by default in new projects,\nand you should keep it unless you have a very good reason not to.
\nI’ve enabled time zone support. Am I safe?
\nMaybe. You’re better protected from DST-related bugs, but you can still\nshoot yourself in the foot by carelessly turning naive datetimes into aware\ndatetimes, and vice-versa.
\nIf your application connects to other systems – for instance, if it queries\na web service – make sure datetimes are properly specified. To transmit\ndatetimes safely, their representation should include the UTC offset, or\ntheir values should be in UTC (or both!).
\nFinally, our calendar system contains interesting edge cases. For example,\nyou can’t always subtract one year directly from a given date:
\n>>> import datetime\n>>> def one_year_before(value): # Wrong example.\n... return value.replace(year=value.year - 1)\n...\n>>> one_year_before(datetime.datetime(2012, 3, 1, 10, 0))\ndatetime.datetime(2011, 3, 1, 10, 0)\n>>> one_year_before(datetime.datetime(2012, 2, 29, 10, 0))\nTraceback (most recent call last):\n...\nValueError: day is out of range for month\nTo implement such a function correctly, you must decide whether 2012-02-29\nminus one year is 2011-02-28 or 2011-03-01, which depends on your business\nrequirements.
\nHow do I interact with a database that stores datetimes in local time?
\nSet the TIME_ZONE option to the appropriate\ntime zone for this database in the DATABASES setting.
This is useful for connecting to a database that doesn’t support time zones\nand that isn’t managed by Django when USE_TZ is True.
My application crashes with TypeError: can't compare offset-naive\nand offset-aware datetimes – what’s wrong?
Let’s reproduce this error by comparing a naive and an aware datetime:
\n>>> from django.utils import timezone\n>>> aware = timezone.now()\n>>> naive = timezone.make_naive(aware)\n>>> naive == aware\nTraceback (most recent call last):\n...\nTypeError: can't compare offset-naive and offset-aware datetimes\nIf you encounter this error, most likely your code is comparing these two\nthings:
\na datetime provided by Django – for instance, a value read from a form or\na model field. Since you enabled time zone support, it’s aware.
a datetime generated by your code, which is naive (or you wouldn’t be\nreading this).
Generally, the correct solution is to change your code to use an aware\ndatetime instead.
\nIf you’re writing a pluggable application that’s expected to work\nindependently of the value of USE_TZ, you may find\ndjango.utils.timezone.now() useful. This function returns the current\ndate and time as a naive datetime when USE_TZ = False and as an aware\ndatetime when USE_TZ = True. You can add or subtract\ndatetime.timedelta as needed.
I see lots of RuntimeWarning: DateTimeField received a naive\ndatetime (YYYY-MM-DD HH:MM:SS) while time zone support is active\n– is that bad?
When time zone support is enabled, the database layer expects to receive\nonly aware datetimes from your code. This warning occurs when it receives a\nnaive datetime. This indicates that you haven’t finished porting your code\nfor time zone support. Please refer to the migration guide for tips on this process.
\nIn the meantime, for backwards compatibility, the datetime is considered to\nbe in the default time zone, which is generally what you expect.
\nnow.date() is yesterday! (or tomorrow)
If you’ve always used naive datetimes, you probably believe that you can\nconvert a datetime to a date by calling its date()\nmethod. You also consider that a date is a lot like a\ndatetime, except that it’s less accurate.
None of this is true in a time zone aware environment:
\n>>> import datetime\n>>> import zoneinfo\n>>> paris_tz = zoneinfo.ZoneInfo("Europe/Paris")\n>>> new_york_tz = zoneinfo.ZoneInfo("America/New_York")\n>>> paris = datetime.datetime(2012, 3, 3, 1, 30, tzinfo=paris_tz)\n# This is the correct way to convert between time zones.\n>>> new_york = paris.astimezone(new_york_tz)\n>>> paris == new_york, paris.date() == new_york.date()\n(True, False)\n>>> paris - new_york, paris.date() - new_york.date()\n(datetime.timedelta(0), datetime.timedelta(1))\n>>> paris\ndatetime.datetime(2012, 3, 3, 1, 30, tzinfo=zoneinfo.ZoneInfo(key='Europe/Paris'))\n>>> new_york\ndatetime.datetime(2012, 3, 2, 19, 30, tzinfo=zoneinfo.ZoneInfo(key='America/New_York'))\nAs this example shows, the same datetime has a different date, depending on\nthe time zone in which it is represented. But the real problem is more\nfundamental.
\nA datetime represents a point in time. It’s absolute: it doesn’t depend\non anything. On the contrary, a date is a calendaring concept. It’s a\nperiod of time whose bounds depend on the time zone in which the date is\nconsidered. As you can see, these two concepts are fundamentally different,\nand converting a datetime to a date isn’t a deterministic operation.
\nWhat does this mean in practice?
\nGenerally, you should avoid converting a datetime to\ndate. For instance, you can use the date\ntemplate filter to only show the date part of a datetime. This filter will\nconvert the datetime into the current time zone before formatting it,\nensuring the results appear correctly.
If you really need to do the conversion yourself, you must ensure the\ndatetime is converted to the appropriate time zone first. Usually, this\nwill be the current timezone:
\n>>> from django.utils import timezone\n>>> timezone.activate(zoneinfo.ZoneInfo("Asia/Singapore"))\n# For this example, we set the time zone to Singapore, but here's how\n# you would obtain the current time zone in the general case.\n>>> current_tz = timezone.get_current_timezone()\n>>> local = paris.astimezone(current_tz)\n>>> local\ndatetime.datetime(2012, 3, 3, 8, 30, tzinfo=zoneinfo.ZoneInfo(key='Asia/Singapore'))\n>>> local.date()\ndatetime.date(2012, 3, 3)\nI get an error “Are time zone definitions for your database\ninstalled?”
If you are using MySQL, see the Time zone definitions section\nof the MySQL notes for instructions on loading time zone definitions.
\nI have a string "2012-02-21 10:28:45" and I know it’s in the\n"Europe/Helsinki" time zone. How do I turn that into an aware\ndatetime?
Here you need to create the required ZoneInfo instance and attach it to\nthe naïve datetime:
>>> import zoneinfo\n>>> from django.utils.dateparse import parse_datetime\n>>> naive = parse_datetime("2012-02-21 10:28:45")\n>>> naive.replace(tzinfo=zoneinfo.ZoneInfo("Europe/Helsinki"))\ndatetime.datetime(2012, 2, 21, 10, 28, 45, tzinfo=zoneinfo.ZoneInfo(key='Europe/Helsinki'))\nHow can I obtain the local time in the current time zone?
\nWell, the first question is, do you really need to?
\nYou should only use local time when you’re interacting with humans, and the\ntemplate layer provides filters and tags\nto convert datetimes to the time zone of your choice.
\nFurthermore, Python knows how to compare aware datetimes, taking into\naccount UTC offsets when necessary. It’s much easier (and possibly faster)\nto write all your model and view code in UTC. So, in most circumstances,\nthe datetime in UTC returned by django.utils.timezone.now() will be\nsufficient.
For the sake of completeness, though, if you really want the local time\nin the current time zone, here’s how you can obtain it:
\n>>> from django.utils import timezone\n>>> timezone.localtime(timezone.now())\ndatetime.datetime(2012, 3, 3, 20, 10, 53, 873365, tzinfo=zoneinfo.ZoneInfo(key='Europe/Paris'))\nIn this example, the current time zone is "Europe/Paris".
How can I see all available time zones?
\nzoneinfo.available_timezones() provides the set of all valid keys for\nIANA time zones available to your system. See the docs for usage\nconsiderations.