Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Python Bytearray Modification: In-Place Editing

Learn how to modify Python bytearray objects in place: element assignment, slice editing, and methods such as append, extend, insert, and pop, with working code examples.

~4 min readPython
#bytearray#bytes#mutable-sequences#binary-data
A diagram showing a bytearray sequence with an element being replaced in place, illustrating mutable byte sequence editing in Python.

Python's bytearray type provides a mutable sequence of integers in the range 0–255. Unlike bytes, which is immutable, a bytearray can be modified in place after creation. Understanding in-place bytearray modification is essential for protocol handling, binary file processing, and buffer manipulation where data must be changed without allocating a new object each time.

What Makes bytearray Different From bytes

The bytes type is immutable: any operation that appears to change it actually creates a new object. The bytearray type exposes the same sequence interface but allows direct mutation of its elements. This distinction matters when you need to update binary data repeatedly, because in-place modification avoids the allocation and copy cost of building a new bytes object for every change.

python
data = bytearray(b"hello") data[0] = ord("H") print(data) # bytearray(b'Hello')

The same operation on a bytes object would raise a TypeError, because item assignment is not supported on immutable sequences.

Modifying Individual Elements by Index

Assigning to an index replaces a single byte. The assigned value must be an integer between 0 and 255; assigning a value outside that range raises a ValueError, and assigning a non-integer raises a TypeError.

python
buf = bytearray(b"\x00\x01\x02\x03") buf[1] = 0xFF print(buf) # bytearray(b'\x00\xff\x02\x03')

Negative indices work as they do for other Python sequences, addressing elements from the end of the buffer:

python
buf[-1] = 0xAA print(buf) # bytearray(b'\x00\xff\x02\xaa')

This is the most direct form of in-place bytearray modification and is commonly used when parsing binary structures where specific offsets must be patched.

Slice Assignment for Bulk Changes

Slice assignment replaces a range of elements with the contents of an iterable. The iterable can be a bytes object, another bytearray, a list of integers, or any iterable of integers in the valid range.

python
buf = bytearray(b"abcdef") buf[1:4] = b"XYZ" print(buf) # bytearray(b'aXYZef')

The replacement slice does not need to match the length of the original slice. The buffer grows or shrinks to accommodate the new data:

python
buf = bytearray(b"abcdef") buf[1:4] = b"XY" print(buf) # bytearray(b'aXYef')

Extended slice assignment with a step requires the replacement iterable to have exactly the same length as the slice being replaced:

python
buf = bytearray(b"abcdef") buf[::2] = b"ACE" print(buf) # bytearray(b'AbCdEf')

If the lengths do not match, Python raises a ValueError. This constraint exists because extended slices cannot change the length of the sequence.

In-Place Methods: append, extend, insert, and More

The bytearray type provides several methods that modify the buffer in place. These are useful when building binary data incrementally.

append adds a single byte to the end:

python
buf = bytearray() buf.append(0x48) buf.append(0x69) print(buf) # bytearray(b'Hi')

extend appends all elements from an iterable:

python
buf = bytearray(b"Hello") buf.extend(b", world") print(buf) # bytearray(b'Hello, world')

insert places a byte at a given position, shifting subsequent elements to the right:

python
buf = bytearray(b"ac") buf.insert(1, ord("b")) print(buf) # bytearray(b'abc')

pop removes and returns the last byte, or the byte at a specified index:

python
buf = bytearray(b"abc") last = buf.pop() print(last, buf) # 99 bytearray(b'ab')

remove deletes the first occurrence of a given value:

python
buf = bytearray(b"aab") buf.remove(ord("a")) print(buf) # bytearray(b'ab')

clear empties the buffer entirely:

python
buf = bytearray(b"data") buf.clear() print(buf) # bytearray(b'')

Most of these methods return None because they mutate the object in place rather than returning a new sequence. The exception is pop, which returns the removed byte.

Converting Between bytes and bytearray

When you receive a bytes object from a socket, file, or API and need to modify it, convert it to a bytearray first:

python
raw = b"\x00\x01\x02" mutable = bytearray(raw) mutable[0] = 0xFF

Converting back to bytes produces an immutable snapshot:

python
final = bytes(mutable)

The conversion copies the underlying data. If you only need to read the buffer without modifying it, keep it as bytes to avoid the copy. If you need frequent in-place edits, converting once to bytearray and modifying in place is usually cheaper than repeatedly creating new bytes objects.

Performance and Memory Behavior of In-Place Modification

The primary advantage of bytearray over repeated bytes concatenation is that in-place operations do not allocate a new object for each change. Concatenating bytes with + creates a new object and copies both operands, which becomes expensive when done in a loop.

python
# Repeated concatenation allocates a new bytes object each iteration result = b"" for i in range(1000): result += bytes([i % 256])

The equivalent bytearray version extends the existing buffer, reallocating only when the internal capacity is exhausted:

python
result = bytearray() for i in range(1000): result.append(i % 256)

The bytearray amortizes growth in the same way a list does, so the cost of many appends is linear in the total number of bytes added. This behavior is relevant when assembling large binary payloads such as network frames or file chunks.

One caveat is that bytearray stores the data in a contiguous block. Very large buffers that grow repeatedly may trigger reallocation and copying, but the amortized cost remains acceptable for most workloads. If you know the final size in advance, preallocating with bytearray(n) and assigning by index avoids reallocation entirely.

Common Pitfalls When Modifying bytearray

Assigning a value outside the valid byte range is a frequent mistake:

python
buf = bytearray(b"\x00") buf[0] = 256 # ValueError: byte must be in range(0, 256)

Remember that bytearray elements are integers, not characters. Assigning a single-character string raises a TypeError:

python
buf[0] = "A" # TypeError: 'str' object cannot be interpreted as an integer

Use ord("A") or the integer value directly.

When slicing with a step, the replacement length must match the slice length exactly. This is a common source of ValueError in code that handles variable-length binary fields.

Another subtle issue is that bytearray compares equal to bytes with the same content, but the types remain distinct. Code that checks type(data) is bytes will reject a bytearray, so use isinstance(data, (bytes, bytearray)) when either type is acceptable.

Finally, be aware that memoryview objects created from a bytearray reflect subsequent modifications. If you hold a memoryview and then mutate the underlying bytearray, the view sees the new data. This can be useful for zero-copy processing but also means you must not mutate the buffer while another component is reading through the view without synchronization.

Try matching browser tools

All tools

Small utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Python guides

More in Python

All Python guides

The guides filed next to this one in Python, in library order.