How to Resolve Python "ValueError: time data does not match format"

The ValueError: time data 'X' does not match format 'Y' is a common exception encountered when parsing strings into datetime objects using Python's datetime.strptime() method. It signals a mismatch between the actual structure of your date string ('X') and the format code ('Y') you provided to interpret it. The parser expects the string to exactly follow the pattern defined by the format code.

This guide explains the common reasons for this mismatch and provides clear solutions to ensure successful date string parsing.

Understanding the Error: strptime and Format Codes

Python's datetime.strptime(date_string, format) function works by taking a string (date_string) and converting it into a datetime object based on a specific format pattern you provide. This format string uses special directive codes (like %Y for a 4-digit year, %m for month number, %d for day, %H for hour, etc.) to tell the function exactly how the date_string is structured.

The ValueError occurs when the parser, following your format instructions, encounters a part of the date_string that doesn't align with what the format code expects at that position.

Common Cause 1: Incorrect Directive Order or Value

Swapped Month (%m) and Day (%d)

This is very common, especially with ambiguous formats like MM-DD-YYYY vs. DD-MM-YYYY. If your format code expects Month-Day but the string provides Day-Month (and the day value is > 12), the error occurs.

from datetime import datetime

date_string = '2025-24-09' # Day 24, Month 09

try:
    dt_object = datetime.strptime(date_string, '%Y-%m-%d')
    print(dt_object)
except ValueError as e:
    print(e)

correct_format = '%Y-%d-%m'
dt_object_fixed = datetime.strptime(date_string, correct_format)
print(f"\nCorrectly parsed with '{correct_format}': {dt_object_fixed}")

Incorrect Year Directive (%y vs. %Y)

Using %y (2-digit year) in the format when the string has a 4-digit year (%Y), or vice-versa, will cause a mismatch.

from datetime import datetime

date_string_4_year = '2025-09-24'
date_string_2_year = '25-09-24'

try:
    dt_object = datetime.strptime(date_string_4_year, '%y-%m-%d')
    print(dt_object)
except ValueError as e:
    print(f"Error 1: {e}")

dt_object_fixed1 = datetime.strptime(date_string_4_year, '%Y-%m-%d')
print(f"\nParsed '{date_string_4_year}' with '%Y-%m-%d': {dt_object_fixed1}")

try:
    dt_object = datetime.strptime(date_string_2_year, '%Y-%m-%d')
    print(dt_object)
except ValueError as e:
    print(f"Error 2: {e}")

dt_object_fixed2 = datetime.strptime(date_string_2_year, '%y-%m-%d')
print(f"Parsed '{date_string_2_year}' with '%y-%m-%d': {dt_object_fixed2}")

Common Cause 2: Incorrect Separators or Literal Characters

The format string must include all literal characters (like hyphens -, slashes /, spaces , colons :) exactly as they appear in the date string.

from datetime import datetime

date_string = "24/09/2025 10:30"
incorrect_format = "%d-%m-%Y %H:%M" # Uses hyphens

try:
    dt_object = datetime.strptime(date_string, incorrect_format)
    print(dt_object)
except ValueError as e:
    print(e)

correct_format = "%d/%m/%Y %H:%M"
dt_object_fixed = datetime.strptime(date_string, correct_format)
print(f"\nCorrectly parsed with '{correct_format}': {dt_object_fixed}")

Ensure every non-directive character in your format string corresponds precisely to the character in the same position in the date string.

Common Cause 3: String Contains Extra or Missing Data

The date string must contain exactly the information specified by the format string, and nothing more (unless accounted for).

from datetime import datetime

date_string_extra = "2025-09-24 10:30:00 EST"
format_str = '%Y-%m-%d %H:%M:%S' # Doesn't account for ' EST'

try:
    dt_object = datetime.strptime(date_string_extra, format_str)
    print(dt_object)
except ValueError as e:
    print(f"Error 1: {e}")


date_string_missing = "2025-09-24 10:30"
format_str_expects_seconds = '%Y-%m-%d %H:%M:%S' # Expects seconds

try:
    dt_object = datetime.strptime(date_string_missing, format_str_expects_seconds)
    print(dt_object)
except ValueError as e:
    print(f"Error 2: {e}")

format_str_fixed2 = '%Y-%m-%d %H:%M' # Matches the string without seconds
dt_object_fixed2 = datetime.strptime(date_string_missing, format_str_fixed2)
print(f"\nParsed missing seconds OK: {dt_object_fixed2}")

Solution: Ensure Format String Exactly Matches the Date String

The fundamental solution to all these causes is to carefully construct your format string so that it is an exact template for your date_string. Every directive (%Y, %m, etc.) and every literal character (-, /, , :) must correspond precisely in order and type to the content of the date string.

Debugging Tips

• Print Both: print(f"Date String: '{date_string}'") and print(f"Format Code: '{format_string}'") right before the strptime call. Visually compare them character by character.
• Check Docs: Refer to the official Python documentation for strftime() and strptime() format codes to ensure you're using the correct directives (%Y vs %y, %m vs %b, etc.).
• Simplify: Start with a simpler format string matching just the beginning of your date string and gradually add more components until it breaks. This helps isolate the mismatch.
• Check for Whitespace: Hidden leading/trailing whitespace in the date_string can cause mismatches if not included in the format. Use date_string.strip() if appropriate.

Alternatives for More Flexible Parsing (Briefly)

If your date strings might have varying formats or are less structured, strptime's strictness can be challenging. Consider these alternatives:

Using dateutil.parser

The third-party python-dateutil library offers a very flexible parse() function that can often guess the format automatically.

from dateutil import parser

try:
    dt = parser.parse("24 Sep 2025 10:30 PM")
    print(f"dateutil parsed: {dt}")     # Output: 2025-09-24 22:30:00
    dt2 = parser.parse("2025/09/24")
    print(f"dateutil parsed: {dt2}")    # Output: 2025-09-24 00:00:00
except ValueError:
    print("dateutil failed to parse.")

Using Pandas to_datetime

If using the Pandas library, pd.to_datetime() is powerful and can infer formats or accept a format argument similar to strptime. Setting infer_datetime_format=True can help performance with consistent formats.

import pandas as pd

try:
    dt = pd.to_datetime("2025-09-24 10:30:15.123")
    print(f"Pandas parsed: {dt}") # Output: 2025-09-24 10:30:15.123000
except ValueError:
    print("Pandas failed to parse.")

These are alternatives to strptime, not fixes for using strptime incorrectly.

Conclusion

The ValueError: time data 'X' does not match format 'Y' arises when using datetime.strptime() because the provided date_string does not exactly conform to the structure defined by the format string. To resolve this error:

1. Verify Directive Order: Ensure %m, %d, %Y, etc., are in the correct sequence corresponding to the date string.
2. Use Correct Directives: Use %Y for 4-digit years, %y for 2-digit years, and consult docs for others (%H, %I, %p, etc.).
3. Match Separators and Literals: Ensure all characters like -, /, :, , etc., in the format string match those in he date string precisely.
4. Account for All Data: Make sure the format string covers all parts of the date string and doesn't expect data that isn't present.

Carefully aligning the format string with the date_string structure is key to successfully using strptime().