Python file.reconfigure() Method

Beginner
6 min read
Updated: Nov 2026
3 examples
text file method

Definition

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.

python
f.reconfigure(errors="replace")
f.reconfigure(encoding="latin-1")
f.reconfigure(line_buffering=True)
CallWhat it does
f.reconfigure(errors="replace")Unencodable characters become ? on write.
f.reconfigure(encoding="latin-1")Decode or encode with Latin-1 from now on.
f.reconfigure(line_buffering=True)Flush automatically whenever a newline is written.

All arguments are keyword-only. Giving encoding without errors resets errors to "strict".

Method signatures
python
TextIOWrapper.reconfigure(*, encoding=None, errors=None, newline=None,
                          line_buffering=None, write_through=None)   # -> None

Parameters

ParameterDescription
encodingNew codec name, such as "utf-8" or "latin-1".
errorsNew error handler: "strict", "replace", "ignore", "backslashreplace", and others.
newlineNew newline mode, with the same meaning as in open().
line_bufferingTrue to flush whenever a write contains a newline.
write_throughTrue to pass every write straight to the binary buffer.

Return Value

Return ValueDescription
NoneThe 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())

How It Works

  1. Starting settings. The file reports the encoding passed to open() and the default error handler strict.
  2. Change mid-stream. reconfigure() flushes tea 3 with UTF-8, then switches both settings for later writes.
  3. Replacement character. ASCII cannot store e-acute, so errors="replace" writes ? instead of raising UnicodeEncodeError.
  4. 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))

How It Works

  1. Latin-1 bytes. The byte \xe9 is e-acute in Latin-1 but an incomplete sequence in UTF-8.
  2. Strict UTF-8 fails. Reading with the wrong encoding raises UnicodeDecodeError.
  3. Reconfigure first. Switching to Latin-1 before any read is allowed and decodes all 11 characters.
  4. 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()))

How It Works

  1. Off by default. Files opened normally do not flush at each newline, so line_buffering starts as False.
  2. Switch it on. After reconfigure(line_buffering=True), any write containing a newline triggers a flush.
  3. 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.

Next: file.seek()

Move the file position to an offset from the start, the current position, or the end.

seek() →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

13 people found this page helpful