dict.clear()

Empty the dict in place — the SAME object becomes empty. All references see the change.

Dict methodPython 1.0+Live demo
Common call
cache.clear()
Returns
None — dict is empty afterwards
Replaces
`for k in list(d): del d[k]` — but clearer and faster
Watch out
different from `d = {}` — clear mutates every reference; `= {}` rebinds only the local name
dict.clear()
→ None

Demo

Live evaluation
Try:
Inputs
dictdictkey: value pairs
Output
{'a': '1', 'b': '2', 'c': '3'}.clear()
None

clear empties the dict in place. Python actually returns None; the demo shows the resulting state (always empty) so you can see the effect. The subtle and important thing NOT visible here: any other name pointing at the same dict object sees the change too. That is the difference from `d = {}`, which only rebinds the local name.

Common patterns

Reset a cache
Every consumer holding a reference sees the empty cache immediately.
shared_cache.clear()
Between test runs
Empty a module-level dict without swapping it out.
def setup():
    STATE.clear()
    STATE.update(defaults)
Empty a nested dict without breaking outer references
clear on the inner dict keeps the outer structure intact.
user["profile"].clear()   # profile dict empties, user still points at it

Examples

1. Basic
d = {"a": 1, "b": 2} d.clear() d
Returns
{}
2. Already empty
{}.clear()
Returns
None # no error
3. Returns None
{"a": 1}.clear()
Returns
None
4. Affects all references
d = {"a": 1} e = d d.clear() e
Returns
{} # e sees the change too
5. Assignment does NOT
d = {"a": 1} e = d d = {} e
Returns
{"a": 1} # e still points at the original

Pitfalls

1. clear() is NOT the same as `d = {}`
clear mutates the existing dict — every reference sees it become empty. `d = {}` creates a NEW empty dict and rebinds the local name; every other reference still points at the original (which is unchanged).
Rebind misses aliases
shared = {"count": 5}
local = shared
shared = {}
local
{"count": 5} # aliases still see the old data
clear reaches everyone
shared = {"count": 5}
local = shared
shared.clear()
local
{} # every alias sees empty
2. The `d = d.clear()` bug
clear() returns None. Assigning its result back sets your variable to None — the same class of bug as sort, extend, and update.
Now d is None
d = {"a": 1}
d = d.clear()
print(d)
None
Just clear
d.clear()   # mutate, keep name
{}
3. Clearing while iterating raises
Modifying the dict during iteration is a RuntimeError, and clear is a modification.
Runtime error
for k in d:
    if predicate(k):
        d.clear()
RuntimeError: dictionary changed size during iteration
Iterate a snapshot
for k in list(d):
    ...
safe
4. Views held elsewhere become empty views
A dict_keys / dict_values / dict_items view is a live view. After clear(), any held view iterates nothing.
View empty after clear
k = d.keys()
list(k)     # ["a", "b"]
d.clear()
list(k)     # []
the view is live; it reflects the empty state
Snapshot for isolation
k = list(d.keys())
d.clear()
k           # ["a", "b"] — a list, not a view
unchanged

When to use

Use it
  • Resetting a shared / module-level / cache dict without rebinding
  • Preparing a container between test runs or workflow stages
  • Emptying a nested dict without breaking outer references
  • Any "empty this and keep the identity" requirement
Reach for something else
  • You want a fresh, independent empty dict → `d = {}`
  • You have a specific key to remove → dict.pop / del d[key]
  • Iterating and removing selectively → build a new dict with a comprehension
  • You need to record what was cleared → snapshot before clearing

Notes

Complexity
O(n) — walks and releases every entry
Return
None; the dict is mutated in place
CPython impl
Objects/dictobject.c :: dict_clear
Memory
Frees entries; the hash table itself may keep some capacity
Thread-safe
Not safe under concurrent iteration or mutation

FAQ

clear() mutates the SAME dict — every reference to it sees it become empty. `d = {}` creates a NEW empty dict and rebinds just the local name; every other reference still points at the original.

History

1.0
clear() has been part of dict since Python 1.0.