Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Python bytearray: Mutable Bytes for Binary Data

Learn how to create, modify, and convert Python bytearray objects for binary data handling, with practical examples for network packets, file editing, and common pitfalls.

~5 min readPython
#bytearray#bytes#binary data#mutable sequence
Diagram showing a bytearray as a mutable sequence of bytes with modification arrows

Python's bytearray type is a mutable sequence of integers in the range 0–255, where each integer represents one byte. Unlike the immutable bytes type, you can modify a bytearray in place by assigning to individual indexes, replacing slices, appending, extending, inserting, and removing items. That makes it useful for binary protocols, file editing, and other low-level data work where repeatedly creating new bytes objects is wasteful.

What Is a bytearray in Python?

A bytearray is a built-in type that represents a mutable sequence of integers in the range 0–255. Each element is a single byte. It behaves like a list of integers, but with the constraint that every value must fit in one byte. It is not hashable, while bytes is immutable and hashable. This distinction matters when choosing which type to use: bytearray is the right choice when you need a buffer you can modify in place.

Creating bytearray Objects

You can create a bytearray in several ways, depending on the source data.

From an Iterable of Integers

Pass a list or tuple of integers between 0 and 255:

python
ba = bytearray([65, 66, 67]) print(ba) # bytearray(b'ABC')

From a String with Encoding

When you have text, you must specify an encoding to convert it to bytes:

python
ba = bytearray('hello', 'utf-8') print(ba) # bytearray(b'hello')

From a bytes Object

Copy an existing bytes or bytearray:

python
original = b'\x00\x01\x02' ba = bytearray(original) print(ba) # bytearray(b'\x00\x01\x02')

From a Size (Zero-Filled)

Create a bytearray of a given length, filled with zero bytes:

python
ba = bytearray(4) print(ba) # bytearray(b'\x00\x00\x00\x00')

This is useful when you need a preallocated buffer that you will fill later.

Modifying bytearray Content

Because bytearray is mutable, you can change its contents using index assignment, slicing, and methods like append, extend, insert, pop, and remove.

Index Assignment

Assign a new byte value to a specific position:

python
ba = bytearray(b'abc') ba[0] = 120 # 'x' print(ba) # bytearray(b'xbc')

The assigned value must be an integer in the range 0–255. Assigning a non-integer raises TypeError; assigning an out-of-range integer raises ValueError.

Slice Assignment

Replace a slice with another sequence of bytes:

python
ba = bytearray(b'abcdef') ba[1:3] = b'XYZ' print(ba) # bytearray(b'aXYZdef')

The replacement can be any iterable of integers or a bytes-like object. The slice length does not need to match the replacement length; the bytearray will grow or shrink accordingly.

Appending and Extending

Add single bytes or multiple bytes at the end:

python
ba = bytearray(b'abc') ba.append(100) # 'd' ba.extend(b'ef') print(ba) # bytearray(b'abcdef')

append takes an integer, while extend accepts an iterable of integers or a bytes-like object.

Inserting and Removing

Insert a byte at a specific index, or remove by value:

python
ba = bytearray(b'abc') ba.insert(1, 120) # 'x' print(ba) # bytearray(b'axbc') ba.remove(120) # removes the first occurrence of 120 print(ba) # bytearray(b'abc')

pop removes and returns the last byte (or a specific index if provided).

Converting Between bytes, bytearray, and Other Types

You often need to move between bytes, bytearray, and text. The conversion methods are straightforward.

bytes to bytearray and Back

python
b = b'\x00\x01\x02' ba = bytearray(b) back = bytes(ba) print(back == b) # True

Converting a bytearray to bytes creates a new immutable copy. This is a common step before sending data over a socket or writing to a file, where immutability is preferred.

bytearray to String

Use .decode() with an appropriate encoding:

python
ba = bytearray(b'hello') s = ba.decode('utf-8') print(s) # 'hello'

Hexadecimal Representation

For debugging or logging, .hex() returns a string of hex digits:

python
ba = bytearray(b'\x00\x0f\xff') print(ba.hex()) # '000fff'

Using memoryview

A memoryview allows you to access the buffer without copying, which is useful for zero-copy operations:

python
ba = bytearray(b'\x01\x02\x03') mv = memoryview(ba) mv[0] = 9 print(ba) # bytearray(b'\x09\x02\x03')

Changes made through the memoryview are reflected in the original bytearray because they share the same underlying buffer.

bytes vs bytearray: Choosing the Right Type

The choice between bytes and bytearray depends on whether you need to modify the data after creation. The table below summarizes the key differences.

Propertybytesbytearray
MutabilityImmutableMutable
HashableYesNo
Memory overheadSlightly lowerSlightly higher
Use caseRead-only data, dict keysIn-place modification
Thread safetySafe to shareRequires external locking

Use bytes when the data will not change after creation, such as a fixed header or a cryptographic key. Use bytearray when you need to parse and modify a buffer incrementally, like building a network packet or editing a binary file in memory.

Performance and Memory Considerations

bytearray avoids the cost of repeatedly creating new bytes objects when you need to change parts of a buffer. Modifying a bytearray in place is generally faster than concatenating or slicing bytes objects, especially for large data. However, bytearray objects typically have a small memory overhead compared to bytes because the mutable buffer needs extra bookkeeping.

When you convert a bytearray to bytes (e.g., to pass to an API that expects immutability), a copy is made. If you need to avoid that copy, consider using memoryview to expose the buffer without copying.

One performance pitfall is resizing. Appending or inserting can trigger reallocation when the internal capacity is exceeded. If you know the final size in advance, preallocate with bytearray(size) and then fill it via slice assignment to avoid repeated resizing.

Common Use Cases for bytearray

bytearray shines in scenarios that require low-level binary manipulation.

Network Packet Construction

When building a custom protocol, you often need to assemble a header, modify fields, and send the result. A bytearray lets you update fields in place:

python
packet = bytearray(20) # preallocate packet[0:4] = (0x12345678).to_bytes(4, 'big') packet[4:6] = (100).to_bytes(2, 'big') # send over socket sock.sendall(bytes(packet))

Binary File Editing

Reading a file into a bytearray, modifying specific offsets, and writing it back is efficient:

python
with open('image.bin', 'r+b') as f: data = bytearray(f.read()) data[10:14] = b'\x00\x00\x00\x00' # clear a field f.seek(0) f.write(data)

Image Processing

Pixel data can be manipulated directly as a byte array, especially for formats like BMP or raw RGB:

python
pixels = bytearray(width * height * 3) # RGB for i in range(0, len(pixels), 3): pixels[i] = 255 - pixels[i] # invert red channel

Handling Edge Cases and Errors

Working with bytearray introduces a few common pitfalls.

Value Out of Range

Assigning an integer outside 0–255 raises ValueError:

python
ba = bytearray(1) ba[0] = 256 # ValueError: byte must be in range(0, 256)

Index Out of Range

Like lists, accessing or assigning an invalid index raises IndexError.

Encoding Errors

When creating a bytearray from a string, an unknown character for the specified encoding raises UnicodeEncodeError. Always use an encoding that can represent the string, or handle the error explicitly.

Mutability and Hashability

Because bytearray is mutable, it cannot be used as a dictionary key or stored in a set. If you need a hashable representation, convert it to bytes first.

Concurrency

If multiple threads modify the same bytearray, you must synchronize access with a lock. The mutable nature makes it unsafe for concurrent writes without external coordination.

Understanding these edge cases helps you avoid subtle bugs when using bytearray in production code. The type is a powerful tool for binary data, but it requires care with boundaries and concurrency.

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.