Python bytes.maketrans() Method

Beginner
5 min read
Updated: Nov 2026
3 examples
static method

Definition

bytes.maketrans(from, to) returns a bytes object of length 256 that translate() can use. Position b in the table holds the byte that b should become.

Every byte in from maps to the byte at the same position in to; all other positions map to themselves. Both arguments must be bytes-like and of equal length.

bytes.maketrans() is a static method: call it on the class itself, as bytes.maketrans(...), not on a particular bytes object. bytearray.maketrans() exists too and builds the same kind of table.

Syntax

Call it on the bytes class with two equal-length bytes objects.

python
table = bytes.maketrans(from_bytes, to_bytes)
result = data.translate(table)
CallWhat it does
bytes.maketrans(b"ab", b"AB")A 256-byte table mapping a to A and b to B.
bytes.maketrans(b"", b"")The identity table, equal to bytes(range(256)).
bytes.maketrans(b"ab", b"x")Raises ValueError: lengths differ.

If a byte appears twice in from, the later mapping wins.

Method signatures
python
static bytes.maketrans(from, to)
# from, to: bytes-like objects of the same length
# returns a bytes object of length 256

Parameters

ParameterDescription
fromThe bytes to be replaced.
toThe replacement bytes, position by position. Must be the same length as from.

Return Value

Return ValueDescription
bytesA 256-byte translation table.

Python Examples

Example 1 — Inspect a Translation Table

Build a small table, look at two of its 256 entries, and apply it.

python
table = bytes.maketrans(b"abc", b"xyz")

print(type(table).__name__, len(table))
print(table[ord("a")], table[ord("d")])
print(b"aabbccdd".translate(table))

How It Works

  1. Always 256 bytes. The table has one entry for every possible byte value, whatever the size of the mapping.
  2. Changed entry. Position 97 (a) holds 120, the code for x.
  3. Identity entry. Position 100 (d) holds 100, so d maps to itself.
  4. Apply it. translate() swaps a, b, and c while the two d bytes stay.

Example 2 — Unify Field Separators

A record mixes ; and | as separators. Map both to a comma in one pass and then split.

python
row = b"id;name|score"
table = bytes.maketrans(b";|", b",,")

print(row.translate(table))
print(row.translate(table).split(b","))

How It Works

  1. Many to one. Two different source bytes may map to the same target byte.
  2. Single pass. Translation handles both separators at once instead of two replace() calls.
  3. Ready to split. With one separator left, split() returns the three fields.

Example 3 — The Identity Table and the Length Rule

An empty mapping gives the identity table, mismatched lengths fail, and bytearray.maketrans() builds a table too.

python
identity = bytes.maketrans(b"", b"")
print(identity == bytes(range(256)))

try:
    bytes.maketrans(b"ab", b"x")
except ValueError:
    print("from and to must have the same length")

print(bytearray.maketrans(b"0", b"O")[48])

How It Works

  1. Identity table. With nothing to map, entry b is simply b, the same as bytes(range(256)).
  2. Lengths must match. Two source bytes and one target byte cannot be paired, so ValueError is raised.
  3. bytearray version. Entry 48 (the digit zero) now holds 79, the code for the letter O.

Frequently Asked Questions

A bytes object of length 256 that maps each byte value to its replacement, for use with translate().
It is a static method: it does not need an existing object. bytes.maketrans(a, b) is the normal way to call it.
ValueError is raised.
You cannot. Build the mapping with maketrans() and pass the bytes to delete as the second argument of translate().
Yes. Any 256-byte bytes-like table works with both bytes.translate() and bytearray.translate().

Next: bytes.partition()

Split at the first separator into a 3-tuple: before, separator, after.

partition() →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

11 people found this page helpful