datetime Module — Use datetime for date/time basics (intro)

Computers have needed to track dates and times since their earliest days. When you log into a website, send a text message, or schedule a reminder, the software behind the scenes is storing and comparing timestamps. Before standardized libraries existed, programmers had to write their own date-handling code from scratch — accounting for leap years, time zones, and the varying number of days in each month. This led to countless bugs and even famous disasters like the Y2K bug, where storing years as two digits threatened to cause widespread computer failures at the turn of the millennium.

Python's datetime module was introduced as part of the standard library to give every Python programmer a reliable, well-tested toolkit for working with dates and times. Instead of reinventing the wheel, you can import a single module and immediately start creating date objects, calculating time differences, and formatting dates for display.

The central question the datetime module answers is simple but important: How do we represent, manipulate, and display dates and times in a way that is both accurate and easy for programmers to use? In this lesson, you will learn the core classes in the datetime module and how to put them to work in your own programs.

The datetime module is built around a handful of classes, each designed to represent a different aspect of time. Understanding these classes is the foundation for everything you will do with dates in Python. You always begin by importing the module with from datetime import date, datetime, timedelta (or similar import statements), and then you create objects from these classes.

As you can see in the diagram above, the datetime class sits at the intersection of date and time. This means a single datetime object carries all six attributes — year, month, day, hour, minute, and second — making it the most versatile class for everyday use. The timedelta class stands alongside them as the tool for measuring and calculating differences in time.

Working with the datetime module follows a consistent pattern: you import the classes you need, create objects, and then access their attributes or call their methods. Let's walk through the key operations one by one.

Importing and Creating Objects

The module is named datetime, and it contains a class also called datetime. This can be confusing at first! The most common import style is from datetime import date, datetime, timedelta so you can use the class names directly. To create a specific date, you pass the year, month, and day as arguments: my_date = date(2025, 6, 15). For a full date and time, use my_dt = datetime(2025, 6, 15, 9, 30, 0) where the last three numbers are hour, minute, and second.

Getting the Current Date and Time

One of the most useful features is grabbing the current date and time. The method datetime.now() returns a datetime object representing the exact moment the code runs. Similarly, date.today() returns just today's date without any time information.

Accessing Attributes

Once you have a datetime or date object, you can access its parts using dot notation. For example, if now = datetime.now(), then now.year gives the year, now.month gives the month (1–12), now.day gives the day, and now.hour gives the hour in 24-hour format.

Formatting with strftime()

The strftime() method (short for 'string format time') converts a datetime object into a formatted string. You pass a format string using special codes: %Y for a four-digit year, %m for a two-digit month, %d for the day, %H for the hour (24-hour), and %M for the minute. For example, now.strftime("%B %d, %Y") might produce "January 15, 2025".

Arithmetic with timedelta

You can add or subtract timedelta objects to shift dates forward or backward. Writing date.today() + timedelta(days=30) gives you the date 30 days from now. You can also subtract two date or datetime objects to get a timedelta: difference = date2 - date1 and then access difference.days to see how many days apart they are.

The strftime() method is incredibly flexible. The table below lists the most commonly used format codes you will encounter. Each code starts with a percent sign and is replaced by the corresponding date/time component when the string is generated.

Notice that literal characters like the comma, spaces, and the word "at" in the format string are passed through unchanged. Only codes starting with % are replaced. This gives you full control over how dates appear to your users — whether you want "01/15/2025" (American format), "15/01/2025" (European format), or something completely custom.

Let's write a short program that calculates how many days remain until a specific event — for instance, the last day of school on June 6, 2025. This example uses multiple datetime concepts together.

The datetime module is powerful, but it is important to understand both what it does well and where it falls short. Knowing its limitations helps you pick the right tool for the job.

The basics you have learned here form the foundation for more advanced date and time handling. As your projects grow in complexity, you will encounter situations where you need features beyond what we have covered today. The table below previews how introductory datetime concepts connect to more advanced topics.

As you move into web development, data science, or app building, you will find that datetime is used almost everywhere. Database records are timestamped with datetime values. APIs send dates as ISO 8601 strings (like "2025-01-15T14:30:00Z") that you will parse using strptime(). Mastering the basics now gives you a strong foundation for all of these future applications.