Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Python String Maketrans: Character Translation Tables

Learn how str.maketrans builds translation tables for str.translate, enabling efficient single-pass character mapping and deletion in Python.

~3 min readPython
#Python#str.translate#character mapping#string manipulation
Editorial illustration of a Python translation table mapping source characters to replacement characters in a single pass.

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. It 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 mapping is normally used only as an argument to str.translate().

The Three Calling Forms of str.maketrans

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

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

python
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. The two strings must have the same length; otherwise Python raises ValueError.

python
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.

python
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.

python
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. Unlike chained replacements, the mapping is applied in a single pass over the original string, so you do not construct a new string for each individual replacement.

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.

python
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 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.

python
table = str.maketrans({ ord("s"): "ss", ord("x"): None, }) print("saxophone".translate(table)) # ssaophone

Here s expands to two characters and x is removed. Values can also be plain integer code points for one-to-one replacements. Use None in the dict when you need to delete specific characters without a separate deletion string.

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.