datetime module is a built-in module in Python that allows us to work with dates and times easily. Inside the module we can find a few classes, but the most used ones are
This usually means that we work with the
datetime class inside the
datetime module—somewhat confusing, but that's why you'll normally see things like
datetime.datetime when looking at Python code that uses this.
What is a
Put simply, a
datetime object is one that stores information about a specific point in time. Information such as year, month, day, hour, minute, and second. With all that information, we can use a
datetime object to refer to one particular moment in time. For example:
import datetime today = datetime.datetime(year=2019, month=12, day=23, hour=11, minute=49, second=30) print(today) # 2019-12-23 11:49:30
In addition to storing data about the specific point in time, it also has methods that help us interact with or process that data in a way that makes sense.
For example, given two
datetime objects you can compare them to see which one is further into the future.
import datetime today = datetime.datetime(year=2019, month=12, day=23, hour=11, minute=49, second=30) tomorrow = datetime.datetime(year=2019, month=12, day=24, hour=11, minute=49, second=30) print(today > tomorrow) # False
Here we would print
today is in the past, relative to
tomorrow. This is how we can compare two dates, for example to tell whether something happened in the past.
How to get today's date
Because getting today's date is so common, the
datetime class comes with a method you can use to get a new
datetime object for today's date:
import datetime print(datetime.datetime.now()) # 2019-12-23 11:54:13.151509
You can also use
datetime.datetime.today() to get the current time and date, but it can sometimes be less precise. Also, it does now allow us to give it timezone information (more on that later!)
Notice that when we're doing this, we get microseconds as well as the other time measures. This can be unnecessary, but when dealing with computers it can sometimes be useful.
How to modify dates
You can't add two dates together, as that seldom makes sense. For example, what should happen if you add "today" to "today"?
import datetime print(datetime.datetime.now() + datetime.datetime.now()) # Error
Instead, when you want to change a date—for example by adding a few days to it—we use the
timedelta class. A "delta" in mathematics means a "change", so that's where the name comes from.
import datetime today = datetime.datetime.now() one_week = datetime.timedelta(days=7) print(today + one_week) # 2019-12-30 11:58:52.073407
You can use
timedelta with these arguments:
But the object itself will only store
microseconds. All other arguments will be converted to those (e.g.
minutes * 60 will be added to
How to display dates
str() function, so that they'll be shown in this format:
import datetime print(datetime.datetime.now()) # 2019-12-23 11:54:13.151509
Sometimes you may want more flexibility regarding how you print it out. Maybe you only want to print out the date portion. Or maybe, just "hours and minutes".
You can do this by using
.strftime(), which stands for "string format time".
import datetime today = datetime.datetime.now() print(today.strftime("%Y-%m-%d") # 2019-12-23 print(today.strftime("%H:%M") # 11:54
Doing this does not modify the
today object at all, it just creates a string representing the date or time as dictated by the "format string" passed.
This is a good reference for all different things you can pass to
How to parse dates
Very similarly to printing dates with a specific format, we can read in dates with a specific format.
For example, let's say your user gives you a string describing today's date:
23-12-2019. Clearly this string is in the format "day-month-year". In Python
We can use
.strptime to parse a date string into a
import datetime user_date = input("Enter today's date: ") # Assume they entered 23-12-2019 today = datetime.datetime.strptime(user_date, "%d-%m-%Y") print(today) # 2019-12-23 00:00:00
The same format strings as we used for
strftime can be used in
What is a timestamp?
A timestamp is the number of seconds that have passed since 1st January, 1970, at midnight.
We use timestamps because it is easier to work with a single number (albeit large) than with many numbers each describing a different measurement.
The timestamp for "2nd January, 1970, at midnight" would be
86400: the number of seconds in one day.
To get a timestamp you can call the
timestamp() method of any
import datetime today = datetime.datetime.now() print(today.timestamp()) # 1577104357.558527
Because it is so common to get the timestamp of right now, we can use the
time module to get it more easily:
import time print(time.time()) # 1577104492.7515678
A timezone is a region where the same standard time is used.
For example, a lot of Western Europe uses the same standard time—Spain, France, Italy, Germany, etc. They are all in the "Central European Time" timezone. In Summer, when daylight savings are in effect, they are all in the "Central European Summer Time" timezone.
If you are running Python in a computer that is using CET, then doing
datetime.datetime.now() would give you the local time of the computer.
However if you grab a different computer that is using Pacific Standard Time, then
datetime.datetime.now() would give you a different time.
That is why it is important to tell the
datetime objects what timezone the time they represent is in: so that no matter what computer is running the code, the time represented will always be the same.
The "central" time is called Universal Time Coordinated (UTC). All other timezones can be described by using UTC as a reference. For example, CET is UTC + 1 hour. PST is UTC - 6 hours.
We would thus write CET as
+01:00, and PST as
We call that the "offset", and it is usually placed after a date and time. For example:
The above time is 11:54 with an offset of 1 hour.
That means that that timezone might be CET (or any other timezone with a +1 hour offset from UTC).
We can calculate the UTC time by subtracting 1 hour from the time, which would put us at 10:54.
Getting the current date and time in UTC
We've learned that you can get the local time like so:
import datetime today = datetime.datetime.now() print(today) # 2019-12-23 15:35:56.133138
When doing this you can ask Python to get you the current time, but translated to a different timezone. Below we pass
.now() so that Python will give us the current time in the UTC timezone.
import datetime today = datetime.datetime.now(datetime.timezone.utc) print(today) # 2019-12-23 15:35:56.133138+00:00
You can see that in my case, the time is the same. That is because at the moment my timezone also has an offset of +00:00, so it matches UTC.
If your timezone does not match UTC, you'll see those two times are different (indeed, the difference will be your timezone's offset from UTC).
Note that when we did
.now() without passing a timezone, our printed string did not contain an offset. But when we did
.now(datetime.timezone.utc), the printed string contained the
Naive vs. aware datetimes
datetime object knows what timezone the date and time it represents is in, then we call that an aware
datetime object. If it doesn't have timezone information, we call that a naive object.
Aware objects represent specific points in time in specific places in the world. Naive objects only represent specific points in time.
Note that working with naive objects can be dangerous because different pieces of code may interpret the naive object to be using a different timezone. For example, some of your code might use a naive object as if it were in UTC. Some other code might use a naive object as if it were in the current, local timezone.
Therefore it's almost always a good idea to store timezone information in your
Converting from one timezone to another using pytz
You can convert from one timezone to another using the built-in
datetime module, but you'll need to tell Python what timezones exist and can be used by writing a class for each timezone that subclasses the
datetime.tzinfo class. You'll also have to do a lot of manual work so that your timezone classes keep track of daylight savings.
Alternatively you can use (and probably should use) the
pytz module for working with timezones in your Python code.
First of all, install
pytz by following their installation instructions or using
pip install pytz.
Getting a timezone from pytz
pytz module comes with a whole database of timezones, accessible by their official names:
import pytz eastern = pytz.timezone("US/Eastern") amsterdam = pytz.timezone("Europe/Amsterdam")
Adding timezone information to a native datetime
If you have a naive
datetime object (from the built-in module), you can use
pytz to add timezone information:
import datetime import pytz eastern = pytz.timezone("US/Eastern") local_time = datetime.datetime.now() print(local_time) # 2020-02-12 11:47:21.817708 eastern_time = eastern.localize(local_time) print(eastern_time) # 2020-02-12 11:47:21.817708-05:00
Note that doing this does not change the time information in the
Converting from one timezone to another
If you have an aware
datetime object and you want to translate it to another timezone, then you can also do this with
import datetime import pytz eastern = pytz.timezone("US/Eastern") amsterdam = pytz.timezone("Europe/Amsterdam") local_time = datetime.datetime.now() eastern_time = eastern.localize(local_time) print(eastern_time) # 2020-02-12 11:47:21.817708-05:00 amsterdam_time = eastern_time.astimezone(amsterdam) print(amsterdam_time) # 2020-02-12 17:47:21.817708+01:00
Now the displayed time has changed because it's the same date and time, but in a different timezone. Both
amsterdam_time refer to the same exact point in time.
You can make sure of that by converting each to UTC yourself. Add 5 hours to
eastern_time and subtract 1 hour from
amsterdam_time to reach a +00:00 offset. You'll see the times are identical.
Dealing with daylight savings
pytz module deals with daylight savings with you. For example the
US/Eastern timezone may sometimes be at
-05:00 and other times at
-04:00, depending on the time of year.
An example of this shown below
Working with dates and times in software applications
Usually I would recommend to always work in UTC in your applications. Ask the users for local time and timezone, and convert it to UTC. Store UTC in your database. Only change back to the user's local time when you are displaying a date and time to them (and only if your users want to see times in their local time).
That way you will not have to worry about timezones within your application logic; only when dealing with user interaction.
pytz module comes with a
pytz.utc timezone that you can use when constructing
datetime objects in order to simplify this:
import datetime import pytz eastern = pytz.timezone("US/Eastern") user_date = datetime.datetime(2020, 4, 15, 6, 0, 0, tzinfo=eastern) utc_date = user_date.astimezone(pytz.utc) print(utc_date) # 2020-04-15 10:56:00+00:00
As long as you always work with UTC, and only convert to the user's local timezone when you are displaying information, it will be relatively simple!
Thank you for reading this blog post on working with dates and times in Python using
pytz. I hope it's been useful!
If you want to learn more about Python as a whole, check out our Complete Python Course. It's a 30-hour video-course that takes you from beginner to expert in Python. We'd love to see you there!