Python String Maketrans: Character Translation Tables

When you need to replace one set of characters with another in a Python string, str.maketrans builds a translation table that str.translate() applies in a single pass. The python string maketrans method is a static method on the str class, and it is the foundation for efficient character-level rewriting without chaining multiple .replace() calls.

What str.maketrans Returns and Why It Matters

str.maketrans returns a translation table: a mapping from Unicode code points to replacement values. That table is consumed by str.translate(), which walks the string once and replaces each character according to the mapping. Characters that are not present in the table are copied unchanged.

Building this mapping by hand is error-prone, especially when you need to delete characters or map a single character to a multi-character string. The method exists to handle those cases with a consistent calling convention, and the resulting table is not meant to be inspected or modified directly.

The Three Calling Forms of str.maketrans

str.maketrans has three overloads, and choosing the wrong one is the most common source of errors.

One argument, a dict. Keys must be Unicode code points (integers), not single-character strings. Values can be a replacement string, an integer code point, or None to delete the character.

table = str.maketrans({ord("a"): "@", ord("o"): "0"})
print("banana".translate(table))  # b@n@n@

Two arguments, two equal-length strings. Each character in the first string maps to the character at the same position in the second string.

table = str.maketrans("aeiou", "AEIOU")
print("hello world".translate(table))  # hEllO wOrld

Three arguments. The third string lists characters to delete after the mapping is applied.

table = str.maketrans("aeiou", "AEIOU", ".,!?")
print("Hello, world!".translate(table))  # HEllO wOrld

The two-argument form is the most common because it reads naturally: the first string is the set of characters to replace, and the second is their replacements. The three-argument form adds deletion, which is useful for stripping punctuation or other fixed character sets.

Applying the Table with str.translate()

str.translate(table) walks the string once and applies the mapping. The table is the only argument, and the result is a new string.

table = str.maketrans("abc", "xyz")
print("abracadabra".translate(table))  # xyrxzxdxyx

Here each a becomes x, each b becomes y, and each c becomes z; every other character is copied unchanged. The important behavior is that the mapping is applied in a single pass. There is no intermediate string created between replacements, which matters when you are replacing many different characters at once.

Deleting Characters with the Third Argument

The three-argument form is the cleanest way to strip a fixed set of characters. Deletion happens after the replacement mapping, so a character that is both mapped and listed for deletion is deleted.

def strip_punctuation(text):
    table = str.maketrans("", "", ".,!?;:")
    return text.translate(table)

print(strip_punctuation("Hello, world; how are you?"))
# Hello world how are you

Passing empty strings for the first two arguments means no replacement occurs; only the deletion set is active. This approach is faster and more readable than chaining a .replace() call for each punctuation mark, and it keeps the deletion rules in one place.

Mapping to None and Multi-Character Strings

The dict form is more flexible than the two-argument form because values can be multi-character strings or None.

table = str.maketrans({
    ord("s"): "ss",