bytearray.append()

Takes a single INT, not a bytes object. That asymmetry — bytearray indexes to ints but slices to bytes — is the thing to internalise about this type.

Bytearray methodPython 3.0+Live demo
Common call
buf.append(0x0a)
Returns
None — the buffer is mutated
Replaces
buf += bytes([byte]), which allocates
Watch out
append(b'a') is a TypeError; it must be an int like 97
bytearray.append(bytebyte — An integer from 0 to 255. Anything outside that range raises ValueError; a bytes object raises TypeError.type: int · required)
→ None

Demo

Live evaluation
Try:
Inputs
sstrstarting buffer (as text)
byteintbyte value 0-255
Output
[b := bytearray(bytes('abc', 'utf-8')), b.append(100), b][2]
bytearray(b'abcd')

The demo expression looks odd because append returns None — the walrus and the list index exist purely so you can see the resulting buffer instead. Appending 100 adds the letter d, because 100 is its ASCII code. Values outside 0 to 255 raise ValueError, since a byte cannot hold them. Note that non-printable bytes such as 10 and 0 appear as escapes in the output rather than as characters.

Parameters

NameTypeRequiredDescription
byteintyesAn integer from 0 to 255. Anything outside that range raises ValueError; a bytes object 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

Build a buffer byte by byte
The mutable alternative to repeatedly concatenating bytes.
buf = bytearray()
for value in values:
    buf.append(value)
Terminate a record
Adding a single delimiter byte needs no allocation.
buf.append(0x0a)   # newline
Accumulate then freeze
Build mutably, hand out something immutable.
return bytes(buf)

Examples

1. Append a letter
b = bytearray(b'abc') b.append(100) b
Returns
bytearray(b'abcd')
2. Returns None
bytearray(b'abc').append(100)
Returns
None
3. Onto empty
b = bytearray() b.append(97) b
Returns
bytearray(b'a')
4. Out of range
bytearray(b'abc').append(256)
Returns
ValueError: byte must be in range(0, 256)
5. bytes rejected
bytearray(b'abc').append(b'd')
Returns
TypeError
6. Use ord for a char
b.append(ord('d'))
Returns
appends 100

Pitfalls

1. It takes an int, not a bytes object
The most common bytearray mistake. append adds ONE byte, so it wants that byte as a number — passing b'd' is a TypeError even though it is exactly one byte long.
bytes rejected
buf.append(b'd')
TypeError: 'bytes' object cannot be interpreted as an integer
Pass the value
buf.append(ord('d'))   # or 100
appends d
2. Values must fit in a byte
Anything outside 0 to 255 raises ValueError. Arithmetic that overflows — adding to a byte value without masking — fails here rather than wrapping.
Out of range
buf.append(300)
ValueError: byte must be in range(0, 256)
Mask it
buf.append(300 & 0xFF)
appends 44
3. Appending several at once needs extend
append handles exactly one byte. Passing an iterable is a TypeError, and looping when extend would do is slower and noisier.
Iterable rejected
buf.append([1, 2])
TypeError
Use extend
buf.extend([1, 2])
both added
4. It returns None
Like every in-place mutator, assigning the result replaces your buffer with None. The same family of bug as list.sort and list.append.
Buffer becomes None
buf = buf.append(100)
None
Just call it
buf.append(100)
buf is updated

When to use

Use it
  • Building a binary buffer incrementally
  • Adding a single delimiter or terminator byte
  • Any loop where bytes concatenation would copy repeatedly
Reach for something else
  • Adding several bytes → extend
  • Adding at a position → insert
  • The buffer never changes → build bytes directly

Notes

Complexity
O(1) amortised — the buffer over-allocates and occasionally reallocates
Return
None; the bytearray is mutated in place and keeps its identity
CPython impl
Objects/bytearrayobject.c :: bytearray_append
Memory
Grows the internal buffer geometrically, so repeated appends are cheap
Thread-safe
Not safe under concurrent mutation of the same buffer

FAQ

Because a bytearray is a sequence of INTEGERS. Indexing one gives an int, and appending one takes an int. The confusion comes from slicing, which gives bytes back — the two operations genuinely differ.

b = bytearray(b'abc')
b[0]     # 97, an int
b[0:1]   # b'a', a bytes object

History

3.0
bytearray introduced as the mutable counterpart to bytes.