Introduction

Replacing a line in a file sounds simple, but the right implementation depends on whether you want to match exact lines, replace only the first match, or preserve the file safely if something fails mid-write. In Python, the safest general pattern is to write a new file and replace the original only after the rewrite succeeds.

The Safe Rewrite Pattern

Most text files are small enough to process line by line into a temporary file. That gives you a clean failure boundary.

1from pathlib import Path
2import tempfile
3import os
4
5
6def replace_line(path: str, old: str, new: str) -> None:
7    src = Path(path)
8
9    with tempfile.NamedTemporaryFile("w", delete=False, encoding="utf-8", dir=src.parent) as tmp:
10        with src.open("r", encoding="utf-8") as f:
11            for line in f:
12                tmp.write(new + "\n" if line.rstrip("\n") == old else line)
13
14    os.replace(tmp.name, src)
15
16
17replace_line("config.txt", "DEBUG=false", "DEBUG=true")

This rewrites the file safely and then atomically swaps the temporary file into place.

Replace Only the First Matching Line

Sometimes you want only one replacement, not every identical line.

1from pathlib import Path
2
3
4def replace_first_line(path: str, old: str, new: str) -> None:
5    lines = Path(path).read_text(encoding="utf-8").splitlines(True)
6    replaced = False
7
8    with open(path, "w", encoding="utf-8") as f:
9        for line in lines:
10            if not replaced and line.rstrip("\n") == old:
11                f.write(new + "\n")
12                replaced = True
13            else:
14                f.write(line)

That keeps the change narrowly scoped when repeated identical lines exist in the file.

Match by Pattern Instead of Exact Equality

If the target line contains variable content, a regex or prefix match is more useful than exact comparison.

1import re
2from pathlib import Path
3
4
5def replace_setting(path: str, key: str, value: str) -> None:
6    pattern = re.compile(rf"^{re.escape(key)}=.*$")
7    lines = Path(path).read_text(encoding="utf-8").splitlines()
8    updated = [f"{key}={value}" if pattern.match(line) else line for line in lines]
9    Path(path).write_text("\n".join(updated) + "\n", encoding="utf-8")
10
11
12replace_setting("app.env", "PORT", "8080")

This is a better fit for config-style files where the value changes but the key identifies the line.

Be Careful With Newlines and Encoding

Line replacement bugs often come from newline handling, not from the replacement logic itself. If you strip line endings and forget to restore them, the rewritten file may end up with merged lines or inconsistent formatting.

Encoding matters too. If the file is not UTF-8, open it with the correct encoding or you may corrupt the contents during rewrite.

When fileinput Is Good Enough

Python’s fileinput module supports in-place editing and is convenient for quick scripts.

1import fileinput
2
3for line in fileinput.input("config.txt", inplace=True):
4    if line.rstrip("\n") == "DEBUG=false":
5        print("DEBUG=true")
6    else:
7        print(line, end="")

This is fine for lightweight automation, but the explicit temporary-file approach is easier to control in production code.

Preserve File Semantics, Not Just Text

Some files carry meaning in line order, trailing newlines, or comment formatting. A replacement script that changes those incidentally can still break the consuming tool even though the target line was updated correctly.

That is why line replacement should be treated as a file-editing operation, not just a string substitution exercise.

Common Pitfalls

The biggest mistake is reading and writing the same file handle at once without a safe rewrite strategy.

Another issue is forgetting whether you want to replace all matches or only the first one.

A third problem is mishandling newlines and encoding, which can corrupt the file even when the line-matching logic is correct.

Summary

• The safest general approach is rewrite-to-temp and then replace the original file.
• Decide whether you need exact line matching, pattern matching, or first-match-only behavior.
• Preserve newline style and file encoding intentionally.
• Use fileinput for quick scripts, but prefer explicit file replacement for robust tooling.
• Treat file rewriting as a data-integrity task, not just a string operation.