bytearray.extend()

The bulk form of append. Unlike append it DOES accept a bytes object, because bytes is itself an iterable of ints — an inconsistency worth remembering.

Bytearray methodPython 3.0+Live demo
Common call
buf.extend(chunk)
Returns
None — the buffer is mutated
Replaces
a loop of append calls, or buf += chunk
Watch out
every item must be 0 to 255; a str raises even though it is iterable
bytearray.extend(iterableiterable — Any iterable of ints in 0 to 255 — a list, a range, another bytes or bytearray. A str raises TypeError.type: iterable · required)
→ None

Demo

Live evaluation
Try:
Inputs
sstrstarting buffer (as text)
morelistbyte values, comma separated
Output
[b := bytearray(bytes('abc', 'utf-8')), b.extend([100, 101]), b][2]
bytearray(b'abcde')

Every value in the iterable is appended in order, so 100 and 101 add the letters d and e. An empty iterable is a harmless no-op rather than an error. As with append, each value must fit in a byte — and one out-of-range number rejects the ENTIRE call, leaving the buffer untouched rather than partially extended.

Parameters

NameTypeRequiredDescription
iterableiterableyesAny iterable of ints in 0 to 255 — a list, a range, another bytes or bytearray. A str raises TypeError.

Return value

None — Returns None — the buffer grows in place. The demo wraps the call so the resulting buffer is visible.

Common patterns

Accumulate chunks from a stream
The standard read loop for assembling a payload.
buf = bytearray()
while chunk := sock.recv(4096):
    buf.extend(chunk)
Append another buffer
bytes and bytearray are both accepted directly.
buf.extend(header)
Add encoded text
Encode first, since a str is rejected.
buf.extend('héllo'.encode('utf-8'))

Examples

1. Two bytes
b = bytearray(b'abc') b.extend([100, 101]) b
Returns
bytearray(b'abcde')
2. Another bytes
b = bytearray(b'ab') b.extend(b'cd') b
Returns
bytearray(b'abcd')
3. Empty is fine
b = bytearray(b'abc') b.extend([]) b
Returns
bytearray(b'abc')
4. From a range
b = bytearray() b.extend(range(3)) b
Returns
bytearray(b'\x00\x01\x02')
5. str rejected
bytearray().extend('ab')
Returns
TypeError
6. Out of range
bytearray().extend([256])
Returns
ValueError: byte must be in range(0, 256)

Pitfalls

1. A str is rejected even though it is iterable
Iterating a str gives characters, not ints, so extend refuses rather than guessing an encoding. The error is confusing because the argument clearly IS iterable.
str rejected
buf.extend('ab')
TypeError: expected iterable of integers; got: 'str'
Encode first
buf.extend('ab'.encode('utf-8'))
both bytes added
2. One bad value rejects the whole call
A single out-of-range item raises and NOTHING is added — extend buffers the values before committing them. Worth knowing precisely because the opposite would be a reasonable guess for an in-place mutator.
Nothing added
buf = bytearray()
buf.extend([1, 2, 256])
# ValueError
buf
bytearray(b'') # not partially extended
Filter or clamp
buf.extend(v & 0xFF for v in values)
every value fits
3. Confused with append
append adds ONE byte and takes an int; extend adds MANY and takes an iterable. Passing an iterable to append, or a bare int to extend, both raise.
int rejected
buf.extend(100)
TypeError: can't extend bytearray with int
Use append
buf.append(100)
one byte added
4. It returns None
Assigning the result replaces your buffer with None — the same trap as append, sort and every other in-place mutator.
Buffer lost
buf = buf.extend(chunk)
None
Just call it
buf.extend(chunk)
buf is updated

When to use

Use it
  • Accumulating chunks read from a socket or file
  • Appending another bytes or bytearray
  • Adding several byte values at once
Reach for something else
  • A single byte → append is clearer
  • Adding at a position → insert
  • The result never changes → build bytes with join instead

Notes

Complexity
O(k) for k added bytes, amortised — the buffer over-allocates
Return
None; the bytearray is mutated in place
CPython impl
Objects/bytearrayobject.c :: bytearray_extend
Memory
May reallocate; growth is geometric so repeated extends stay cheap
Thread-safe
Not safe under concurrent mutation of the same buffer

FAQ

Because bytes IS an iterable of ints — iterating it yields values from 0 to 255, exactly what extend wants. append needs a single int, and a bytes object is not one, even when it holds only one byte.

buf.extend(b'cd')     # fine
buf.append(b'd')      # TypeError

History

3.0
bytearray introduced as the mutable counterpart to bytes.