Skip to content
Keep backslashes literal in regular-expression replacements

Keep backslashes literal in regular-expression replacements

November 19, 2026

A replacement string passed to re.sub() has its own escape and group-reference syntax. Raw-string notation preserves backslashes while Python creates the string, but the regex replacement parser still interprets them. Return the text from a callback when those characters are data.

Set up

Tested on Linux with CPython 3.12.14. Use Bash, Python 3.12 or newer, a text editor, and the mktemp, rm and rmdir utilities. No packages or network access are needed. Keep the same terminal open and stop if setup fails. Run without -O so the assertions remain enabled.

start_dir="$PWD"
work_dir="$(mktemp -d)" || exit 1
cd -- "$work_dir" || exit 1

Run the example

Save as literal_regex_replacement.py:

import re

pattern = re.compile(r"\{\{\s*value\s*\}\}")
template = "first={{value}}; second={{ value }}"
replacement = r"C:\new\report"

interpreted = pattern.sub(replacement, template)
literal = pattern.sub(lambda match: replacement, template)
expected = "first=" + replacement + "; second=" + replacement
assert literal == expected
assert interpreted != literal
print("String replacement:", repr(interpreted))
print("Callable replacement:", repr(literal))

group_text = r"\g<0>"
assert pattern.sub(group_text, "{{value}}") == "{{value}}"
assert pattern.sub(lambda match: group_text, "{{value}}") == group_text
assert pattern.sub(lambda match: replacement, "unchanged") == "unchanged"
print("Literal group syntax:", repr(pattern.sub(lambda match: group_text, "{{value}}")))

Run:

python3 -B literal_regex_replacement.py

Observed output:

String replacement: 'first=C:\new\report; second=C:\new\report'
Callable replacement: 'first=C:\\new\\report; second=C:\\new\\report'
Literal group syntax: '\\g<0>'

Keep replacement data out of the template parser

The first replacement turns the path-like text into a value containing a newline and a carriage return. The printed representations make the difference visible: the callback result contains literal backslashes. The group-reference test shows another change a replacement template can make; returning the same text from a callback preserves it exactly.

The callback receives each match and returns the text to insert. This example deliberately ignores that match because every placeholder gets the same value. The substitution reference documents both replacement forms and their escape behavior.

The regex accepts optional whitespace inside the placeholder, allowing both spellings in the example. If the search is just one fixed substring, a plain string replacement is usually simpler.

Separate matching from output encoding

Pattern escaping and replacement handling solve different problems. Do not pass replacement data through the pattern-escaping helper as a general repair; it is designed for literal text inside regex patterns.

This callback preserves characters in the replacement value. It does not quote them for HTML, SQL, shell commands, or another output format. Apply the destination’s own encoding or parameterization rules where needed. This example only transforms in-memory strings, uses a fixed pattern, and opens no paths.

Clean up

Remove the saved file and empty scratch directory. If the directory is not empty, inspect its contents before removing anything else.

rm -- literal_regex_replacement.py
cd -- "$start_dir" || exit 1
rmdir -- "$work_dir"
unset start_dir work_dir

Acknowledgements

This post was created with assistance from AI.

Last updated on