773

In the python built-in open function, what is the exact difference between the modes w, a, w+, a+, and r+?

In particular, the documentation implies that all of these will allow writing to the file, and says that it opens the files for "appending", "writing", and "updating" specifically, but does not define what these terms mean.

codeforester
  • 34,080
  • 14
  • 96
  • 122
flybywire
  • 247,088
  • 187
  • 391
  • 495
  • 12
    The link you provided exactly defines the values. What part about the link you provided could you not see or understand? Could you clarify your question to explain what you didn't understand about the link? – S.Lott Sep 23 '09 at 14:00
  • @ChrisB. - I reported this as bug at http://bugs.python.org/issue19627 – Bulwersator Nov 16 '13 at 18:54
  • 8
    is there no simple and single doc that explains what the + sign means? – Charlie Parker Jun 28 '16 at 00:36

9 Answers9

900

The opening modes are exactly the same as those for the C standard library function fopen().

The BSD fopen manpage defines them as follows:

 The argument mode points to a string beginning with one of the following
 sequences (Additional characters may follow these sequences.):

 ``r''   Open text file for reading.  The stream is positioned at the
         beginning of the file.

 ``r+''  Open for reading and writing.  The stream is positioned at the
         beginning of the file.

 ``w''   Truncate file to zero length or create text file for writing.
         The stream is positioned at the beginning of the file.

 ``w+''  Open for reading and writing.  The file is created if it does not
         exist, otherwise it is truncated.  The stream is positioned at
         the beginning of the file.

 ``a''   Open for writing.  The file is created if it does not exist.  The
         stream is positioned at the end of the file.  Subsequent writes
         to the file will always end up at the then current end of file,
         irrespective of any intervening fseek(3) or similar.

 ``a+''  Open for reading and writing.  The file is created if it does not
         exist.  The stream is positioned at the end of the file.  Subse-
         quent writes to the file will always end up at the then current
         end of file, irrespective of any intervening fseek(3) or similar.
Arnav Borborah
  • 10,781
  • 6
  • 36
  • 77
drAlberT
  • 20,534
  • 5
  • 31
  • 37
  • 3
    I believe you mean the fopen call in the C standard library (which is not a system call) – Eli Courtwright Sep 23 '09 at 13:34
  • 1
    Indeed there are significant differences between the two. Ex: 'a+' in sys call positions the stream at beginning of file, in std lib it positions at end. Fixing link... – Nick Zalutskiy Jan 10 '12 at 00:30
  • 23
    NOTE:Python v3 adds a number of additional modes. [link to docs](http://docs.python.org/3.3/library/functions.html#open) – Alex Mar 29 '13 at 13:55
  • 9
    Noted that `w` and `w+` both can do `The file is created if it does not exist` – Wei Yang Aug 06 '14 at 18:43
  • 5
    On Windows, `b` appended to the mode opens the file in binary mode, so there are also modes like `rb`, `wb`, and `r+b`. Python on Windows makes a distinction between text and binary files; the end-of-line characters in text files are automatically altered slightly when data is read or written. –  Dec 29 '15 at 12:53
  • 9
    am I right to say that the `+` doesn't do something consistent independent if it is `a`,`w` or `r`? Or am I failing to see the pattern? What is the pattern? – Charlie Parker Jun 28 '16 at 00:38
  • 2
    Why are the default Python docs so crappy? https://docs.python.org/2/library/functions.html#open Is there a nice clean set of docs for the built-in functions like the BSD manpage you linked to? – wordsforthewise Apr 06 '17 at 23:28
  • 1
    @CharlieParker: I believe the pattern is "also do the other thing". So, `r+` doesn't just open the file for reading but also for *writing* and `w+`, in turn, doesn't just open it for writing but also for *reading*. Similarly for `a+`. – balu Oct 20 '17 at 12:44
  • `a` does not create a file if it doesn't exit. `a+` surely does. – DirtyBit Mar 25 '19 at 07:52
  • Why does w+ exist? I'm finding that the file is being truncated before I can read it. If I use "r" I can use readline() and get my first line. If I use "w+" readline() returns empty string. – john stamos Jul 24 '19 at 21:40
  • @DirtyBit are you saying that the docs in the answer are wrong? They explicitly say `a` creates the file if it doesn't exist. `a+` seems to just add the ability to read as well as append, but it's not very clear. – Heath Raftery Aug 27 '19 at 23:29
  • 3
    @johnstamos > Why does w+ exist?. Because you might want to do a read with the same file pointer before closing it. – Karuhanga Sep 24 '19 at 10:52
  • These descriptions are somewhat incomplete in my opinion. e.g. `w+` says it truncates but then it doesn't clarify if what that means but in `w` it says it truncates to length zero. Am I suppose to assume the truncation is the same for both? – Charlie Parker Jul 13 '20 at 16:37
  • 1
    @drAlberT then of course this first comment in the docs saying it trucates to zero is redundant and thus prone to confusing the reader. It leads to the very natural question as to why the "to zero" was clarified in one and not the other...regardless, thanks for the comment. – Charlie Parker Jul 13 '20 at 18:27
705

I noticed that every now and then I need to Google fopen all over again, just to build a mental image of what the primary differences between the modes are. So, I thought a diagram will be faster to read next time. Maybe someone else will find that helpful too.

Renato Byrro
  • 3,193
  • 17
  • 28
Andrzej Pronobis
  • 31,072
  • 15
  • 70
  • 87
  • 2
    So the `+` basically means writing. That is weird that the `w` doesn't mean that but it means truncating...(after reading the next answer, it seems `w` writes over and `a` stands for appending. That makes more sense...) Do you have any comments on file creation if it doesn't exist? – Charlie Parker Jun 28 '16 at 00:40
  • File creation happens for all methods _except_ `r` and `r+` (where you are assuming there IS a file to initially read...). – tenfishsticks Jul 29 '16 at 20:08
  • 5
    The `a` description is **wrong**. The writes are always positioned at the end. – Antti Haapala -- Слава Україні Aug 20 '16 at 09:58
  • 15
    @And I believe @Antti is referring to the property `Subsequent writes to the file will always end up at the then current end of file, irrespective of any intervening fseek(3) or similar` which is somewhat stronger than just saying the *initial* position is the end. – jcai Aug 23 '16 at 02:27
  • The plus does not mean "write". With "w" It means create or overwrite, where overwrite means make the file zero bytes to start with even if it had previously had more bytes of content. – DevPlayer Oct 30 '16 at 01:40
  • for those who are wondering about the difference between `r+b` and `w+b`, from the version 3 [documentation](https://docs.python.org/3/library/functions.html#open): `For binary read-write access, the mode 'w+b' opens and truncates the file to 0 bytes. 'r+b' opens the file without truncation.` – kirpit Aug 27 '17 at 15:00
  • 17
    @CharlieParker That there are basically two file operations (read, write). Mode _r_ is primarily for reading, modes _w_, _a_ are primarily for writing. And **the plus sign enables the second operation** for a given mode (simply said). – Jeyekomon Jan 10 '18 at 08:59
  • 59
    For posterity: truncate means to overwrite from the beginning. – Minh Tran Jun 12 '18 at 21:05
  • @MinhTran You are not overwriting existing contents, you are first throwing it away and then write as if there is nothing there. If the file contains the string `aaaaa` and I truncate and write `ttt` to the file, the result wouldn't be `tttaa`, but just `ttt`. – Frank Vel Apr 09 '22 at 06:52
261

Same info, just in table form

                  | r   r+   w   w+   a   a+
------------------|--------------------------
read              | +   +        +        +
write             |     +    +   +    +   +
write after seek  |     +    +   +
create            |          +   +    +   +
truncate          |          +   +
position at start | +   +    +   +
position at end   |                   +   +

where meanings are: (just to avoid any misinterpretation)

  • read - reading from file is allowed

  • write - writing to file is allowed

  • create - file is created if it does not exist yet

  • truncate - during opening of the file it is made empty (all content of the file is erased)

  • position at start - after file is opened, initial position is set to the start of the file

  • position at end - after file is opened, initial position is set to the end of the file

Note: a and a+ always append to the end of file - ignores any seek movements.
BTW. interesting behavior at least on my win7 / python2.7, for new file opened in a+ mode:
write('aa'); seek(0, 0); read(1); write('b') - second write is ignored
write('aa'); seek(0, 0); read(2); write('b') - second write raises IOError

eglease
  • 2,107
  • 8
  • 14
  • 25
industryworker3595112
  • 3,078
  • 1
  • 13
  • 18
  • 14
    Why is there no "Create file if it doesn't exist. If it does exist, position at start, enable read and write"? This is the most obvious use-case for me: I'm storing data in a file. If the file's not there, create it instead of erroring. If there's data in the file I want to read it all from the top, update some stuff then completely re-write the file from 0 for the NEXT TIME I load it. I use `open(file,'a'); close(); open(file,'r+')` to accomplish this. – pinhead Feb 18 '16 at 00:08
  • @pinhead What you are describing is more appropriately handled by opening the file in read mode, loading the contents into memory, and closing it, then opening it afterwards in write mode to write out when you're done. I assume from the use case that you describe that you want the whole file in memory, and this way you don't corrupt the file in case your program terminates before it has time to save and exit. – krs013 Apr 17 '16 at 21:00
  • 2
    What does "truncating" mean in this context? – Charlie Parker Jun 28 '16 at 00:43
  • 3
    @CharlieParker It means that all content of the file is erased (file is made empty) – industryworker3595112 Jun 28 '16 at 06:55
  • 1
    You might want to add a note that with `a` and `a+` writes will *always* happen at the end of the file, irrespective of whether one manually moves the pointer using `seek()`. – balu Oct 20 '17 at 12:47
  • @balu thanks. I didn't know that. Thanks. After some testing - I'm stunned. Seems `a` modes do not play well with `seek` movements. – industryworker3595112 Oct 23 '17 at 06:29
  • 2
    What about updating the table, to include 'x' for Python 3? – Nikos Alexandris Apr 10 '19 at 21:40
  • 1
    @industryworker3595112 as @NikosAlexandris says, the table could include the `x` option introduced in Python 3.3+. I have a (rejected) edit which I hope suffices. – t.y Jun 19 '19 at 05:11
  • 1
    @pinhead the reason is this: why position at the start if you are writing and file already exists? Wouldn't that start overwriting contents? a+ will keep the file pointer at the end for this reason. I can think of one reason to open in read+write mode and create if not exists and also have random access for one reason and that is a fixed-size shared memory mapped file. – nurettin Sep 10 '19 at 12:35
  • This is still accurate in Python 3.8.1. I expanded your table over at https://dev.to/codemouse92/dead-simple-python-working-with-files-lmg (and in my upcoming book); you're welcome to incorporate my changes in if you like. – CodeMouse92 Jan 28 '20 at 21:49
  • I had the same question as @pinhead, and I don't think @krs013 answered it. You can use `a+` to *create* a file that might not exist and use `.seek(0)` to *read* (not write) from the beginning. That way you don't have to use `open(file,'a'); close(); open(file,'r+')`. – Connor Low Aug 05 '20 at 16:04
44

The options are the same as for the fopen function in the C standard library:

w truncates the file, overwriting whatever was already there

a appends to the file, adding onto whatever was already there

w+ opens for reading and writing, truncating the file but also allowing you to read back what's been written to the file

a+ opens for appending and reading, allowing you both to append to the file and also read its contents

Eli Courtwright
  • 176,085
  • 65
  • 206
  • 255
  • 6
    What does "truncating" mean in this context? Does it mean to delete the old data if it had some? Or something else more specific? – Charlie Parker Jun 28 '16 at 00:45
  • 6
    @CharlieParker: Correct - it means that all data in the existing file will be dropped and we begin writing from the beginning of a now-empty file. – Eli Courtwright Jul 13 '16 at 22:34
14
r r+ x x+ w w+ a a+
readable x x x x x
writeable x x x x x x x
default position: start x x x x x x
default position: end x x
must exist x x
mustn't exist x x
truncate (clear file) on load x x
Always write to EOF x x

Mode

t (default) b
str (io.TextIOBase) x
bytes (io.BufferedIOBase) x

If no mode is selected; text mode (t) is used. As such r is the same as rt.

Peilonrayz
  • 2,519
  • 1
  • 22
  • 34
  • What does "Always write to EOF" mean? – qff Oct 19 '21 at 10:47
  • 1
    @qff EOF stands for End Of File. The "always" means even if you `seek(0)` (move the cursor to the start of the file) then when you `write("foo")` the file will write to the end of the file. Hence why it's called "append" mode. You always append to the end of the file. – Peilonrayz Oct 19 '21 at 10:50
10

I hit upon this trying to figure out why you would use mode 'w+' versus 'w'. In the end, I just did some testing. I don't see much purpose for mode 'w+', as in both cases, the file is truncated to begin with. However, with the 'w+', you could read after writing by seeking back. If you tried any reading with 'w', it would raise an IOError. Reading without using seek with mode 'w+' isn't going to yield anything, since the file pointer will be after where you have written.

Wyrmwood
  • 2,973
  • 25
  • 31
10

I think this is important to consider for cross-platform execution, i.e. as a CYA. :)

On Windows, 'b' appended to the mode opens the file in binary mode, so there are also modes like 'rb', 'wb', and 'r+b'. Python on Windows makes a distinction between text and binary files; the end-of-line characters in text files are automatically altered slightly when data is read or written. This behind-the-scenes modification to file data is fine for ASCII text files, but it’ll corrupt binary data like that in JPEG or EXE files. Be very careful to use binary mode when reading and writing such files. On Unix, it doesn’t hurt to append a 'b' to the mode, so you can use it platform-independently for all binary files.

This is directly quoted from Python Software Foundation 2.7.x.

Goran B.
  • 534
  • 4
  • 11
5

I find it important to note that python 3 defines the opening modes differently to the answers here that were correct for Python 2.

The Python 3 opening modes are:

'r' open for reading (default)
'w' open for writing, truncating the file first
'x' open for exclusive creation, failing if the file already exists
'a' open for writing, appending to the end of the file if it exists
----
'b' binary mode
't' text mode (default)
'+' open a disk file for updating (reading and writing)
'U' universal newlines mode (for backwards compatibility; should not be used in new code)

The modes r, w, x, a are combined with the mode modifiers b or t. + is optionally added, U should be avoided.

As I found out the hard way, it is a good idea to always specify t when opening a file in text mode since r is an alias for rt in the standard open() function but an alias for rb in the open() functions of all compression modules (when e.g. reading a *.bz2 file).

Thus the modes for opening a file should be:

rt / wt / xt / at for reading / writing / creating / appending to a file in text mode and

rb / wb / xb / ab for reading / writing / creating / appending to a file in binary mode.

Use + as before.

NelsonGon
  • 12,469
  • 5
  • 25
  • 52
ingofreyer
  • 924
  • 14
  • 25
0

The open() function opens the file (if possible) and returns the corresponding file object. ..............

The syntax of open() is: open(file, mode='r', buffering=-1, encoding=None, errors=None, newline=None, closefd=True, opener=None)

open(file,mode) mode Parameter It can only be according to the table below :

'r' Open a file for reading. (default)

'w' Open a file for writing. Creates a new file if it does not exist or truncates the file if it exists.

'x' Open a file for exclusive creation. If the file already exists, the operation fails.

'a' Open for appending at the end of the file without truncating it. Creates a new file if it does not exist.

't' Open in text mode. (default)

'b' Open in binary mode.

'+' Open a file for updating (reading and writing)

Milad Koohi
  • 79
  • 1
  • 5