Which File Modes Does Python Support?

The four modes differ in what they do to a file that already exists.

# w creates the file, or empties it when it is already there.
with open('modes.txt', 'w', encoding='utf-8') as handle:
    handle.write('one\n')

# a creates the file, or adds to the end of it.
with open('modes.txt', 'a', encoding='utf-8') as handle:
    handle.write('two\n')

# r only reads the file.
with open('modes.txt', 'r', encoding='utf-8') as handle:
    print(handle.read().split())

# x creates the file only when it is not already there.
try:
    open('modes.txt', 'x', encoding='utf-8').close()
except FileExistsError as error:
    print('FileExistsError:', error)

The output is the list ['one', 'two'] followed by the FileExistsError. The w mode created the file and wrote one line, the a mode added a second line without erasing the first, and the r mode read both of them back. The x mode refused to open a file that already existed.

The summary is short. The r mode reads, the w mode writes and empties the file, the a mode adds to the end, and the x mode creates the file only if it is not there yet. Three of them create the file when it is missing, and only r insists that it already exists. The emptying behaviour of w is the one that surprises people, because opening a file in w mode and then failing before you write anything leaves you with an empty file. A safer pattern is to write to a temporary file and then rename it into place.

The mode argument is a short string, and each character in it is an independent flag.

The first character says what you are doing. The letter r opens the file for reading, and it is the default when you pass no mode at all. The letter w opens the file for writing and empties an existing file to zero length. The letter a opens the file for writing but places every write at the end of the file. The letter x opens the file for writing only when the file does not already exist.

The second character says whether the data is text or bytes. The default is text mode, where the file object deals in str values and handles the encoding and the line endings for you. The letter b opens the file in binary mode, where the data is bytes and no translation happens at all. Text and binary cannot be mixed together, and trying to mix them raises a ValueError at the moment you call open().

The third character is the plus sign, which adds reading and writing permission to the base mode. The mode r+ opens an existing file for both reading and writing without emptying it. The mode w+ empties the file but allows both. The mode a+ allows both and forces every write to the end. One thing to remember about update mode is that the file position is not moved for you after a write, so you normally need to call seek() before you read back what you just wrote.

There are two practical notes. The x mode is the one to reach for when you are creating a file that must not exist yet, because it makes the check and the create into one single operation instead of the unreliable exists-then-open pair. And the default mode for open() is r, so if you forget the mode you get a read-only file rather than an error message.

Every failure mode has its own exception, and all of them inherit from OSError.

# Reading a file that does not exist.
try:
    open('missing.txt', 'r', encoding='utf-8')
except FileNotFoundError as error:
    print('FileNotFoundError:', error)

# Writing to a directory instead of a file.
try:
    open('.', 'w', encoding='utf-8')
except OSError as error:
    print(type(error).__name__)

# Mixing binary and update flags with a text encoding.
try:
    open('missing.txt', 'rb+', encoding='utf-8')
except ValueError as error:
    print('ValueError:', error)

Opening a file that is missing for reading raises FileNotFoundError, and that is a subclass of OSError. Opening a directory for writing raises IsADirectoryError on Linux, and the wider OSError clause catches it on any operating system, because the exact type depends on the system you are running on.

The third case is different in kind. Passing the binary and update flags together with a text-mode encoding is a mistake in your own code rather than a problem with the file system, so Python raises a plain ValueError while it checks the mode string. That happens before the file system is touched at all.

The general rule is simple. Problems with the file system raise subclasses of OSError, and problems with the mode string raise ValueError. When you write careful code, catching OSError covers the whole family, which includes FileNotFoundError, PermissionError, IsADirectoryError, and TimeoutError. Catching the specific subclass lets you handle one situation precisely.