list.clear()

Empties the list itself rather than rebinding the name. Everyone else holding the same list sees it empty too — which is the point, and the trap.

List methodPython 3.3+Live demo
Common call
items.clear()
Returns
None — the list is emptied in place
Replaces
del items[:] and items[:] = []
Watch out
every reference to the list sees the change; items = [] does not do this
list.clear()
→ None

Demo

Live evaluation
Try:
Inputs
listliststarting list
Output
['a', 'b', 'c'].clear()
None

The demo output is None, and that is the real return value — clear mutates the list and gives nothing back. The effect you care about is invisible in the result: every element is removed from the EXISTING list object rather than a new empty one being made, so the list keeps its identity and every other reference to it sees the change. Clearing an already-empty list is a no-op and never raises.

Common patterns

Reuse a buffer between batches
Keeps one list object alive instead of allocating a fresh one each round.
for batch in batches:
    buffer.clear()
    buffer.extend(process(batch))
Empty a shared list everyone can see
The whole reason to prefer clear over rebinding — other holders observe it.
self.pending.clear()   # every reader of self.pending sees empty
Reset without touching the binding
Useful when the list is an attribute or lives in a closure.
state.errors.clear()

Examples

1. Empties it
xs = [1, 2, 3] xs.clear() xs
Returns
[]
2. Returns None
[1, 2, 3].clear()
Returns
None
3. Already empty ok
xs = [] xs.clear() xs
Returns
[]
4. Identity survives
xs = [1] before = id(xs) xs.clear() id(xs) == before
Returns
True
5. Aliases see it
a = [1, 2] b = a a.clear() b
Returns
[]
6. Rebinding does not
a = [1, 2] b = a a = [] b
Returns
[1, 2]

Pitfalls

1. clear() and = [] are not the same thing
The single most useful distinction here. clear empties the object everyone shares; assigning a new empty list only moves your own name, leaving other references pointing at the old, still-full list.
Others still see data
a = [1, 2]
b = a
a = []
b
[1, 2]
Everyone sees empty
a = [1, 2]
b = a
a.clear()
b
[]
2. The `xs = xs.clear()` bug
clear returns None, so assigning its result back replaces your list with None. The same family of mistake as sort, extend and insert.
Now xs is None
xs = [1, 2]
xs = xs.clear()
print(xs)
None
Just clear
xs.clear()
[]
3. Clearing a list you are iterating
Emptying the list mid-loop ends the iteration early, because the iterator is walking positions in a list that just lost them. It fails quietly rather than raising.
Loop stops short
xs = [1, 2, 3]
for x in xs:
    xs.clear()
    print(x)
1 # loop ends immediately
Clear afterwards
for x in xs:
    print(x)
xs.clear()
1 2 3
4. Not available before Python 3.3
list.clear arrived long after dict.clear, so older code uses del xs[:] instead. Both still work, and you will meet the old form in the wild.
AttributeError on 3.2
xs.clear()
AttributeError: 'list' object has no attribute 'clear'
Portable form
del xs[:]
works on every version

When to use

Use it
  • Emptying a list other code also holds a reference to
  • Reusing one buffer across iterations instead of reallocating
  • Resetting a list attribute without rebinding it
Reach for something else
  • You want a fresh, independent list → xs = []
  • Removing only some items → a comprehension or filter
  • Removing one item → remove or pop

Notes

Complexity
O(n) — every element must have its reference dropped
Return
None; the list is mutated in place and keeps its identity
CPython impl
Objects/listobject.c :: list_clear
Memory
Releases the elements; the internal array may be shrunk
Thread-safe
Not safe under concurrent mutation of the same list

FAQ

clear empties the existing list object; xs = [] points the name xs at a brand new one. If anything else refers to the original — another variable, an attribute, a list of lists — clear affects it and rebinding does not.

a = [1, 2]
b = a
a.clear()
b      # []

a = [1, 2]
b = a
a = []
b      # [1, 2]

History

3.3
list.clear added, matching dict.clear and set.clear which already existed.