datetime Module

What Will You Learn
In this article, you will explore the full capabilities of Python’s built-in datetime module. It is the foundation for working with dates and times in Python and an essential tool for any developer working with logs, schedules, reports, or time-based data. You’ll begin by understanding the core classes provided by the module, including datetime, date, time, and timedelta. You’ll learn how to create, manipulate, and format date and time objects. The article also covers how to extract specific components such as year, month, day, hour, and minute from a datetime object.

Every beginner Python developer eventually reaches a point where they need to work with dates or times — whether it’s showing the current date, calculating age, or scheduling a task for the future. That’s why the datetime module deserves your attention early in your learning path. It’s part of the standard library, so there’s no need to install anything, and it gives you powerful tools to handle all things related to time.

If you’ve ever asked “how do I get today’s date?”, “how can I format a timestamp?”, or “how do I compare two times?”, this is the module to master. Learning it will help you avoid time-related bugs and make your applications more robust. In my 20+ years of working with Python, time and date errors have caused some of the most difficult-to-debug issues — but also some of the easiest to avoid, if you know how to use the right tools.

The earlier you understand how to control time in your code, the faster you grow as a Python developer.

What Is the datetime Module in Python?

The datetime module is a built-in Python library that helps you work with dates and times in a structured, reliable way. It allows you to create, modify, compare, and format time-related values. The module includes several core classes like date, time, datetime, and timedelta, each designed for different tasks.

For example, you can use it to get the current date and time, calculate the number of days between two dates, or format a timestamp for display in a user interface. It also supports arithmetic, so you can add or subtract days, hours, or minutes as needed. This makes it ideal for everything from event scheduling to data logging and time-based filtering in databases.

Here are two basic examples to show its usefulness:

    from datetime import datetime

    now = datetime.now()
    print(now)  # Output: 2025-06-02 17:15:45.239187
  

In this example, we import the datetime class from the datetime module and use now() to get the current date and time.

    from datetime import timedelta

    deadline = datetime.now() + timedelta(days=5)
    print(deadline)  # Output: 2025-06-07 17:15:45.239187
  

In this second example, we use the timedelta class to add 5 days to the current date and time, creating a deadline for a task.

These examples illustrate how the datetime module simplifies working with time-related data, making it easier to perform common tasks like getting the current time or calculating future dates.

How to Use the datetime Module in Python?

To use the datetime module, you typically start by importing the classes you need. From there, you can create new date/time objects, perform arithmetic, or convert values to readable formats. The module is consistent, well-documented, and built to handle real-world applications. You don’t need external packages to get started — just Python and a clear understanding of its components.

Here's what beginners should know when using the module:

• datetime: Combines date and time into one object. Use datetime.now() to get the current local timestamp.
• date: Works with year, month, and day only — no time. Great for birthday checks or filtering by calendar day.
• time: Handles hours, minutes, seconds, and microseconds. Useful when you only care about time of day.
• timedelta: Represents the difference between two dates or times. You can add it to or subtract it from a datetime object.
• strftime(): Converts a datetime object into a string using custom formats (like YYYY-MM-DD).
• strptime(): Parses a date/time string and converts it into a datetime object. Perfect for reading user input or data files.

These components work together to give you a complete toolkit for managing time in your applications. You can create new dates, manipulate existing ones, and format them for display or storage. The module is designed to be intuitive, so once you understand the basics, you can quickly build more complex functionality.

How to Install the datetime Module in Python?

One of the advantages of Python’s datetime module is that it’s built-in. That means you don’t need to install it using pip or any package manager — it comes preloaded with every standard Python installation. As soon as Python is installed on your system, you can start using datetime right away.

However, if you're working in a virtual environment, online interpreter, or minimal Docker image, make sure Python is installed properly. To check if you can use datetime, just open your terminal or IDE and run a simple import test.

    # Example 1: Check if datetime is available
    python -c "import datetime; print(datetime.datetime.now())"
  

If you see a timestamp printed in the output, the module is available and ready to use. For virtual environments, simply activate the environment before using datetime:

    # Example 2: Activate your virtual environment
    source venv/bin/activate  # On macOS/Linux
    venv\Scripts\activate     # On Windows
  

If you're using Jupyter Notebook or Google Colab, datetime is also available without installation:

    # Example 3: Use in Jupyter or Colab
    import datetime
    print(datetime.date.today())
  

You don’t install the datetime module — you just use it. That’s the power of Python’s standard library.

How to Import the datetime Module in Python?

To begin working with dates and times in your code, you first need to import the datetime module. This can be done in a few different ways depending on which parts you need. You can import the entire module or just specific classes like datetime, date, or timedelta.

Here are the most common and beginner-friendly import methods:

    # Import the entire module
    import datetime

    now = datetime.datetime.now()
    print(now)
  

In this example, we import the entire datetime module and access the datetime class using the module name. This is useful if you want to keep your code explicit about where each function comes from.

Alternatively, you can import specific classes directly to make your code cleaner and more concise:

    # Import specific class directly
    from datetime import datetime

    now = datetime.now()
    print(now)
  

Iin this case, we import only the datetime class from the module, allowing us to use it without the module prefix. This is often preferred for readability and simplicity.

You can also import multiple classes at once, which is especially useful if you need to work with both dates and times frequently:

    # Import multiple classes at once
    from datetime import datetime, timedelta, date

    print(date.today())
  

In this example, we import datetime, timedelta, and date in one line. This keeps your code organized and allows you to use these classes directly without needing to reference the module each time.

Using direct imports makes your code shorter and cleaner, especially in projects where readability matters. It's also easier to understand for beginners and teammates reviewing your work.

Common Mistakes Made by Beginners

1. Confusing datetime with datetime.datetime

One of the most common beginner mistakes is thinking datetime and datetime.datetime are the same. When you use import datetime, you're importing the module. Inside that module is the datetime class. To access it properly, you need to write datetime.datetime, which can be confusing at first.

    # Wrong
    import datetime
    now = datetime.now()  # AttributeError

    # Correct
    now = datetime.datetime.now()
  

2. Mixing date and datetime Objects

Many beginners try to compare or subtract a datetime object from a date object, expecting it to work. But Python doesn't allow direct operations between these two types without conversion. This leads to TypeError or incorrect results. Always convert your datetime to a date (using .date()) if you want to compare or subtract it from a date object.

    # Wrong
    from datetime import datetime, date
    print(datetime.now() == date.today())  # TypeError

    # Correct
    print(datetime.now().date() == date.today())
  

3. Forgetting to Use timedelta for Time Calculations

Some new developers try to add numbers directly to dates, assuming they can just do date + 1. That’s not how it works. You need to use timedelta for all date arithmetic. Trying to add an integer to a date or datetime results in a TypeError. The right way is to create a timedelta and add it to your date object.

    # Wrong
    from datetime import date
    tomorrow = date.today() + 1  # TypeError

    # Correct
    from datetime import timedelta
    tomorrow = date.today() + timedelta(days=1)
  

4. Ignoring Timezones (Naive vs Aware)

Beginners often don’t understand the difference between naive and aware datetime objects. A naive datetime has no timezone information, while an aware datetime includes it. If you mix them — especially in calculations or comparisons — Python will raise an error. This is critical for applications that serve users across time zones. Always use zoneinfo (Python 3.9+) or pytz to make your datetime objects timezone-aware.

    # Wrong
    from datetime import datetime
    import pytz
    aware = datetime.now(pytz.UTC)
    print(datetime.now() - aware)  # TypeError

    # Correct
    naive = datetime.now()
    aware = naive.replace(tzinfo=pytz.UTC)
    print(aware - aware)
  

5. Using the Wrong Format Codes with strftime() and strptime()

When formatting or parsing dates, beginners often misuse format codes. For example, using lowercase %m (month) instead of %M (minutes) or vice versa. This leads to formatting errors or misinterpreted values. The safest approach is to refer to Python’s official documentation or trusted guides and double-check your format strings. Using incorrect codes silently breaks your logic and returns the wrong output without an obvious error.

    # Wrong
    from datetime import datetime
    date_str = "02-06-2025"
    dt = datetime.strptime(date_str, "%d-%M-%Y")  # Wrong: %M is minutes!

    # Correct
    dt = datetime.strptime(date_str, "%d-%m-%Y")
  

Frequently Asked Questions (FAQ)