deque.maxlen

Set it once in deque(iterable, maxlen) and the deque never grows past it: every append beyond the limit discards the oldest item on the other side. The attribute itself is read-only.

deque attributePython 3.1+Live demo
Common call
window = deque(maxlen=3)
Returns
window.maxlen → 3
Replaces
list + manual "if len(buf) > n: buf.pop(0)"
Watch out
overflow is silent — nothing raises
deque.maxlen
→ int | None

Demo

Live evaluation
Push items one at a time and record what the window holds after each step.
Try:
Inputs
itemslist[str]a stream of items
sizeintwindow size
Code
from collections import deque
window = deque(maxlen=3)
seen = []
for x in ['a', 'b', 'c', 'd', 'e']:
    window.append(x)
    seen.append(''.join(window))
seen
Result
['a', 'ab', 'abc', 'bcd', 'cde']

With size 3 the window fills up (a, ab, abc) and then slides: abc → bcd → cde. With size 0 the deque never holds anything, so every snapshot is an empty string.

Common patterns

Moving average
sum over a bounded window after each new value.
from collections import deque
window = deque(maxlen=5)
for value in readings:
    window.append(value)
    average = sum(window) / len(window)
Last n lines of a file
The docs recipe — a file object is an iterable of lines.
from collections import deque
with open('app.log') as f:
    tail = deque(f, maxlen=20)
Is the window full yet?
Compare the length with maxlen.
if len(window) == window.maxlen:
    process(window)

Examples

1. Read the limit
from collections import deque deque(maxlen=3).maxlen
Returns
3
2. Unbounded deques say None
from collections import deque print(deque([1, 2]).maxlen)
Returns
None
3. Items beyond the limit are dropped
from collections import deque d = deque(maxlen=2) for ch in 'abcd': d.append(ch) d
Returns
deque(['c', 'd'], maxlen=2)
4. Positional maxlen
from collections import deque deque('abcde', 2)
Returns
deque(['d', 'e'], maxlen=2)
5. Negative maxlen
from collections import deque deque(maxlen=-1)
Returns
ValueError: maxlen must be non-negative
6. Read-only
from collections import deque deque(maxlen=2).maxlen = 3
Returns
AttributeError: attribute 'maxlen' of 'collections.deque' objects is not writable

Pitfalls

1. insert() on a full bounded deque
append and extend discard silently, but insert raises instead of choosing an item to drop.
insert when full
from collections import deque
d = deque('ab', maxlen=2)
d.insert(0, 'z')
IndexError: deque already at its maximum size
appendleft
from collections import deque
d = deque('ab', maxlen=2)
d.appendleft('z')
d
deque(['z', 'a'], maxlen=2)
2. Averaging before the window is full
Early windows are shorter than maxlen. Divide by len(window), not by maxlen.
/ maxlen
from collections import deque
w = deque([10], maxlen=4)
sum(w) / w.maxlen
2.5
/ len(window)
from collections import deque
w = deque([10], maxlen=4)
sum(w) / len(w)
10.0

When to use

Use it
  • Sliding windows and moving statistics
  • Recent-history buffers (logs, undo, last N events)
Reach for something else
  • Data you must not lose when full → check len(d) == d.maxlen first, or use queue.Queue(maxsize=n), which blocks

Notes

CPython impl
Set in deque_init; exposed as a read-only member in Modules/_collectionsmodule.c
Versions
The maxlen argument exists since 2.6; the maxlen attribute was added in 3.1 (docs.python.org)
maxlen=0
Allowed: the deque stays empty forever — used to consume iterators

FAQ

collections.deque(maxlen=n). Once it holds n items, each append drops the oldest item from the other end. queue.Queue(maxsize=n) is the alternative that blocks instead of dropping.