reconfigure() changes the settings of an already open text file: its encoding, errors handler, newline mode, line_buffering, and write_through. Settings you leave out stay as they are.
A common use is sys.stdout.reconfigure(encoding="utf-8") to fix console output. Pending writes are flushed first, so text already written keeps its old encoding.
reconfigure() is a method of text files only (io.TextIOWrapper), added in Python 3.7. Binary and raw files have no encoding to change, so they do not have it. No import is needed.
Syntax
Pass only the settings you want to change, as keyword arguments.
New error handler: "strict", "replace", "ignore", "backslashreplace", and others.
newline
New newline mode, with the same meaning as in open().
line_buffering
True to flush whenever a write contains a newline.
write_through
True to pass every write straight to the binary buffer.
Return Value
Return Value
Description
None
The file object itself is changed in place.
Python Examples
Each example works inside a temporary folder that is deleted at the end, so nothing is left on your disk.
Example 1 — Switch to ASCII with Replacement While Writing
Write one line as UTF-8, then reconfigure to ASCII with errors="replace" for the rest of the menu.
python
import os
import tempfile
with tempfile.TemporaryDirectory() as folder:
path = os.path.join(folder, "menu.txt")
with open(path, "w", encoding="utf-8", newline="\n") as f:
print(f.encoding, f.errors)
f.write("tea 3\n")
f.reconfigure(encoding="ascii", errors="replace")
print(f.encoding, f.errors)
f.write("caf\u00e9 4\n")
with open(path, "rb") as f:
print(f.read())
Output
utf-8 strict
ascii replace
b'tea 3\ncaf? 4\n'
How It Works
Starting settings. The file reports the encoding passed to open() and the default error handler strict.
Change mid-stream.reconfigure() flushes tea 3 with UTF-8, then switches both settings for later writes.
Replacement character. ASCII cannot store e-acute, so errors="replace" writes ? instead of raising UnicodeEncodeError.
Verify the bytes. Reading in binary mode shows exactly what reached the disk.
Example 2 — Fix the Encoding Before the First Read
A contacts file saved as Latin-1 fails as UTF-8; reconfiguring right after open() reads it correctly.
python
import os
import tempfile
with tempfile.TemporaryDirectory() as folder:
path = os.path.join(folder, "contacts.txt")
with open(path, "wb") as f:
f.write(b"Jos\xe9 Silva\n")
with open(path, encoding="utf-8") as f:
try:
f.read()
except UnicodeDecodeError:
print("not valid UTF-8")
with open(path, encoding="utf-8") as f:
f.reconfigure(encoding="latin-1")
text = f.read()
print(f.encoding, len(text), ascii(text))
Output
not valid UTF-8
latin-1 11 'Jos\xe9 Silva\n'
How It Works
Latin-1 bytes. The byte \xe9 is e-acute in Latin-1 but an incomplete sequence in UTF-8.
Strict UTF-8 fails. Reading with the wrong encoding raises UnicodeDecodeError.
Reconfigure first. Switching to Latin-1 before any read is allowed and decodes all 11 characters.
ASCII-safe print.ascii() shows the accented letter as \xe9, so the output looks the same in every console.
Example 3 — Turn On Line Buffering for a Live Log
Enable line_buffering on a service log so each finished line is visible to a second reader at once.
python
import os
import tempfile
with tempfile.TemporaryDirectory() as folder:
path = os.path.join(folder, "service.log")
with open(path, "w", encoding="utf-8") as log:
print(log.line_buffering)
log.reconfigure(line_buffering=True)
print(log.line_buffering)
log.write("boot ok\n")
with open(path, encoding="utf-8") as tail:
print(repr(tail.read()))
Output
False
True
'boot ok\n'
How It Works
Off by default. Files opened normally do not flush at each newline, so line_buffering starts as False.
Switch it on. After reconfigure(line_buffering=True), any write containing a newline triggers a flush.
Visible immediately. The second handle reads the complete line while the log is still open, with no explicit flush() call.
Frequently Asked Questions
It changes the encoding, errors, newline, line_buffering, or write_through settings of an open text file without reopening it. It was added in Python 3.7.
Call sys.stdout.reconfigure(encoding="utf-8") at the start of the program, or set the PYTHONUTF8=1 environment variable.
Not once decoded text is waiting in the stream; CPython raises io.UnsupportedOperation. Reconfigure right after open(), before the first read.
No. Only TextIOWrapper has it. Binary files deal in bytes and have no encoding to change.
With line_buffering=True, every write that contains a newline also flushes the buffer, which suits logs that other programs watch.