Python File I/O

Intermediate

A file is persistent data stored outside your running Python program. Python's open() function gives you a file object, which is a stream through which your program can read or write data. A Path identifies where a file is; the file object provides access to its contents.

Open a text file

open() returns a file object. Its default mode is r, which opens an existing file for reading as text. A path-like object, including a pathlib Path, can be passed as the file argument.

from pathlib import Path
from tempfile import TemporaryDirectory

with TemporaryDirectory() as folder:
    path = Path(folder) / 'notes.txt'
    path.write_text('Hello, Python!\n', encoding='utf-8')

    with open(path, 'r', encoding='utf-8') as file:
        print(file.read())

Read file contents

read() reads the requested amount of text from the current stream position. With no size argument, it reads until the end of the file. readline() reads one line, while iterating over a text file reads it line by line.

from pathlib import Path
from tempfile import TemporaryDirectory

with TemporaryDirectory() as folder:
    path = Path(folder) / 'numbers.txt'
    path.write_text('one\ntwo\nthree\n', encoding='utf-8')

    with open(path, encoding='utf-8') as file:
        print(file.readline().strip())
        for line in file:
            print(line.strip())

Write text

Use mode w to open a file for writing. It creates the file if needed and truncates an existing file before writing. write() accepts a string and returns the number of characters written.

from pathlib import Path
from tempfile import TemporaryDirectory

with TemporaryDirectory() as folder:
    path = Path(folder) / 'message.txt'

    with open(path, 'w', encoding='utf-8') as file:
        count = file.write('Hello!\n')
        file.write('Goodbye!\n')

    print(count)
    print(path.read_text(encoding='utf-8'))

Append instead of replacing

Mode a opens a file for writing at the end. Existing contents are preserved, and new writes are appended. Mode x is different: it creates a new file and fails if that file already exists.

from pathlib import Path
from tempfile import TemporaryDirectory

with TemporaryDirectory() as folder:
    path = Path(folder) / 'log.txt'
    path.write_text('first\n', encoding='utf-8')

    with open(path, 'a', encoding='utf-8') as file:
        file.write('second\n')

    print(path.read_text(encoding='utf-8'))

Use with to manage the file

A file object is a resource that should be closed when you are finished with it. The with statement arranges for the file to be closed when the block ends, including when an exception leaves the block. You do not need to explain the context-manager protocol to use this pattern safely.

from pathlib import Path
from tempfile import TemporaryDirectory

with TemporaryDirectory() as folder:
    path = Path(folder) / 'data.txt'

    with open(path, 'w', encoding='utf-8') as file:
        file.write('saved')

    print(file.closed)

Text and binary files

Text I/O works with str and performs encoding and decoding. Binary I/O uses bytes and does not perform text encoding or decoding. Add b to the mode, such as rb or wb, when you need binary data.

from pathlib import Path
from tempfile import TemporaryDirectory

with TemporaryDirectory() as folder:
    path = Path(folder) / 'data.bin'

    with open(path, 'wb') as file:
        file.write(b'ABC')

    with open(path, 'rb') as file:
        data = file.read()

    print(data)
    print(type(data).__name__)

Specify text encoding

When opening text files, specify the encoding when you know which encoding the file uses. For UTF-8 text, use encoding='utf-8'. This makes the conversion between stored bytes and Python strings explicit instead of relying on the platform's locale encoding.

from pathlib import Path
from tempfile import TemporaryDirectory

with TemporaryDirectory() as folder:
    path = Path(folder) / 'greeting.txt'
    with open(path, 'w', encoding='utf-8') as file:
        file.write('Café — Python')

    with open(path, encoding='utf-8') as file:
        print(file.read())

Choose the right file mode

The common modes form a small vocabulary: r reads, w writes and replaces existing contents, a appends, x creates a new file and fails if it already exists, and b selects binary I/O. Add + when you need both reading and writing. Start with the simplest mode that matches the task.

Keep the boundaries clear: pathlib is for paths, open() and file objects are for streams, and encoding determines how text is converted between bytes and strings. More advanced stream types and low-level I/O belong to the io module and are not needed for everyday file handling.