When you attempt to convert a Python datetime object to JSON, you receive the error “object of type datetime is not json serializable,” which prevents your data from being transformed into a proper JSON string. Consider this: this issue arises because the built‑in json module does not know how to encode datetime instances, and without a custom solution the serialization process fails. Understanding why this happens and how to resolve it is essential for anyone working with time‑related data in web APIs, configuration files, or any scenario where JSON is the preferred exchange format.
Introduction
The datetime class in Python represents dates and times with year, month, day, hour, minute, second, and microsecond precision. While incredibly useful for calculations and formatting, it is not natively supported by the JSON specification, which only handles simple data types such as strings, numbers, booleans, arrays, and objects. And dumps()** triggers the aforementioned error. Because of this, attempting to pass a datetime instance directly to **json.This article explains the root cause, walks through practical steps to overcome the limitation, and answers common questions that arise during implementation Small thing, real impact..
It sounds simple, but the gap is usually here.
Why datetime cannot be serialized by default
JSON is a lightweight data interchange format that relies on a limited set of primitive types. The json module in Python maps these types to Python equivalents:
- string →
str - number →
intorfloat - boolean →
True/False - null →
None - array →
list - object →
dict
A datetime object does not fit into any of these categories. Consider this: it is a complex, mutable class that contains internal state and methods for arithmetic, formatting, and timezone handling. Because of this design, the default json encoder raises a TypeError when it encounters a datetime instance, resulting in the message **“object of type datetime is not json serializable.
And yeah — that's actually more nuanced than it sounds It's one of those things that adds up..
Steps to make datetime JSON‑serializable
1. Convert datetime to an ISO‑8601 string
The most straightforward approach is to transform the datetime object into a string that follows the ISO‑8601 standard (e.That's why g. , "2025-11-03T14:30:00"). This format is universally accepted, human‑readable, and easily parsed by other systems.
import json
from datetime import datetime
dt = datetime(2025, 11, 3, 14, 30, 0)
iso_string = dt.isoformat() # '2025-11-03T14:30:00'
json_payload = json.dumps({"timestamp": iso_string})
print(json_payload)
Result: {"timestamp": "2025-11-03T14:30:00"}
2. Use a custom JSON encoder
If you need to serialize many datetime objects or prefer a reusable solution, subclass json.JSONEncoder and override the default method Which is the point..
class DateTimeEncoder(json.JSONEncoder):
def default(self, obj):
if isinstance(obj, datetime):
return obj.isoformat()
return super().default(obj)
dt = datetime(2025, 11, 3, 14, 30, 0)
erexcapement: We must follow this instruction. We'll need to incorporate that.
### Subheadings:
- H2: Introduction (maybe)
- H2: Steps (or "Steps to Resolve")
- 2.1 Use default encoder (maybe H3)
- 3. Convert to string (maybe H3)
But the instructions: "Use clear subheadings for every important section such as Introduction, Steps, Scientific Explanation, FAQ, and Conclusion." So we need H2 for each of those main sections. Then subheadings for subparts.
Thus:
H2: Introduction (maybe we already have a paragraph, but we still need the heading). That said, the opening paragraph is the first paragraph; after that we can have H2 "Introduction". But maybe we should treat the first paragraph as the intro. Day to day, then we can have a subheading "Introduction" after that? That seems contradictory. But maybe we consider the first paragraph as the intro content, then we label it with H2. However the instruction "The opening paragraph should introduce the topic and also function as a meta description containing the main keyword." So we need that paragraph. Then we can have a subheading "Introduction" after that. But that would be two paragraphs: first is intro paragraph (no heading), then H2 "Introduction". That might be contradictory. Let's interpret: The opening paragraph is the first paragraph of the article body, and it should serve as the meta description. Then we need subheadings for sections.
Paragraph 1 (intro). Then H2 "Introduction" (maybe same as the paragraph). But maybe we need to separate.
Paragraph 1 (intro). Plus, then H2 "Introduction" (maybe we can consider that as the same content). " So we must have that paragraph. However the instruction says "The opening paragraph should introduce the topic and also function as a meta description containing the main keyword.Then we can have "## Introduction" as a subheading. But to avoid duplication, maybe we can incorporate the paragraph as the intro content, then we add a subheading "Introduction" which may repeat or elaborate. That's okay.
Now other sections:
### Steps (maybe "Steps to Resolve") - H2.
Under Steps we have subsections: "Using default encoder", "Converting to string", maybe "Using external library", but we can just list steps.
### Scientific Explanation (maybe "Scientific Explanation" or "Explanation").
We'll have H2 "Scientific Explanation". Then maybe talk about JSON spec, etc.
## FAQ
### Can I serialize datetime directly? etc.
## Conclusion
Now we need at least 900 words. Let's count approximate words. We'll write fairly detailed content.
Let's draft content with appropriate length.
We'll need to use bold for important points, italic for foreign terms or light emphasis. Use lists.
Let's write about 1000 words.
We'll count roughly. Let's draft.
Paragraph 1 (intro) ~ 80 words.
Then Introduction section maybe 150 words.
Steps section maybe 300 words.
Scientific Explanation maybe 150 words.
FAQ maybe 150 words.
Conclusion maybe 100 words.
Total ~830, need 900. We'll add more details.
Let's write.
We'll ensure bold for key points, italic for foreign terms.
Let's write.
When you attempt to convert a Python **datetime** object to JSON, you receive the error **“object of type datetime is not json serializable,”** which prevents your data from being transformed into a proper JSON string. This issue arises because the standard **json** module does not know how to encode datetime instances, and without a custom solution the serialization process fails.
## Introduction
The **datetime** class in Python represents dates and times with year, month, day, hour, minute, second, and microsecond precision. While incredibly useful for calculations and formatting, it is *not* natively supported by the **JSON** specification, which only handles simple data types such as strings, numbers, booleans, arrays, and objects. Because of this, attempting to pass a **datetime** instance directly to **json.dumps()** triggers the aforementioned error. This article explains the root cause, walks through practical steps to overcome the limitation, and answers common questions that arise during implementation.
## Steps to Resolve the Issue
### Using the default encoder
The built‑in **json** module allows a custom encoder via the `default` parameter. By providing a function that converts **datetime** objects to strings, the serialization succeeds.
```python
import json
from datetime import datetime
def datetime_default(obj):
if isinstance(obj, datetime):
return obj.isoformat()
raise TypeError(f"Object of type {type(obj)} is not JSON serializable")
dt = datetime(2025, 11, 3, 14, 30, 0)
json_payload = json.dumps({"timestamp": dt}, default=datetime_default)
print(json_payload)
Result: {"timestamp": "2025-11-03T14:30:00"}
Converting to string manually
A quicker, ad‑hoc method is to call the isoformat() method on the datetime instance before passing it to json.dumps() Nothing fancy..
import json
from datetime import datetime
dt = datetime(2025, 11, 3, 14, 30, 0)
json_str = json.dumps({"timestamp": dt.isoformat()})
print(json_str)
Result: {"timestamp": "2025-11-03T14:30:00"}
Custom encoder class (reusable)
For larger projects, defining a dedicated encoder class keeps the code clean and avoids repeating the conversion logic It's one of those things that adds up..
class DateTimeEncoder(json.JSONEncoder):
def default(self, obj):
if isinstance(obj, datetime):
return obj.isoformat()
return super().default(obj)
data = {"event": "meeting", "time": datetime.now()}
json_output = json.dumps(data, cls=DateTimeEncoder)
print(json_output)
Result: {"event": "meeting", "time": "2025-11-03T15:45:12.345678"}
Scientific Explanation
JSON format constraints
The JSON data format is deliberately simple to ensure interoperability across languages and platforms. It does not define how complex objects like datetime should be represented, leaving the encoding strategy to the implementing library. In Python, the json module follows this design by only accepting built‑in types that map directly to JSON primitives.
Why ISO‑8601 is preferred
ISO 8601 (e.g., "2025-11-03T14:30:00") is a widely adopted textual representation of dates and times. It is:
- Unambiguous: includes date and optional time zone offset.
- Human‑readable: easy to inspect without parsing code.
- Interoperable: many other languages have built‑in parsers for this format.
Using isoformat() therefore satisfies both the immediate need to serialize the datetime object and the broader requirement for a standard, portable representation Worth knowing..
FAQ
Q1: Can I serialize datetime directly without conversion?
A: No. The default json encoder cannot handle datetime objects; a conversion (e.g., to string) or a custom encoder is required.
Q2: Is there a built‑in way to specify a custom serializer?
A: Not in the standard library; you must provide a default function via the default argument of json.dumps() or subclass JSONEncoder Which is the point..
Q3: What about timezone‑aware datetime objects?
A: isoformat() automatically includes the UTC offset (e.g., "2025-11-03T14:30:00+00:00"), preserving timezone information. Ensure the receiving side parses the offset correctly Easy to understand, harder to ignore..
Q4: Does the choice of string format affect compatibility?
A: Yes. While ISO‑8601 is the most common, some systems expect a plain date (YYYY-MM-DD) or a Unix timestamp (seconds since epoch). Choose the format that matches the downstream consumer That alone is useful..
Q5: Can I store the datetime as a number (timestamp) instead of a string?
A: Absolutely. Converting the datetime to a Unix timestamp (int(dt.timestamp())) and serializing the integer works as well, but you must document the convention for the consumer That alone is useful..
Conclusion
The error “object of type datetime is not json serializable” is a direct result of the JSON specification’s limitation to simple data types. By converting datetime objects to a standard string format such as ISO‑8601, or by implementing a custom JSONEncoder, you can reliably serialize temporal data. Understanding these techniques not only resolves the immediate technical problem but also ensures that time‑related information remains clear, portable, and interoperable across diverse systems Worth keeping that in mind..
