A safe, atomic file-copy operation
Question:
I need to copy a file from one location to another, and I need to throw an exception (or at least somehow recognise) if the file already exists at the destination (no overwriting).
I can check first with os.path.exists() but it’s extremely important that the file cannot be created in the small amount of time between checking and copying.
Is there a built-in way of doing this, or is there a way to define an action as atomic?
Answers:
There is no way to do this; file copy operations are never atomic and there is no way to make them.
But you can write the file under a random, temporary name and then rename it. Rename operations have to be atomic. If the file already exists, the rename will fail and you’ll get an error.
[EDIT2] rename() is only atomic if you do it in the same file system. The safe way is to create the new file in the same folder as the destination.
[EDIT] There is a lot of discussion whether rename is always atomic or not and about the overwrite behavior. So I dug up some resources.
On Linux, if the destination exists and both source and destination are files, then the destination is silently overwritten (man page). So I was wrong there.
But rename(2) still guarantees that either the original file or the new file remain valid if something goes wrong, so the operation is atomic in the sense that it can’t corrupt data. It’s not atomic in the sense that it prevents two processes from doing the same rename at the same time and you can predict the result. One will win but you can’t tell which.
On Windows, if another process is currently writing the file, you get an error if you try to open it for writing, so one advantage for Windows, here.
If your computer crashes while the operation is written to disk, the implementation of the file system will decide how much data gets corrupted. There is nothing an application could do about this. So stop whining already 🙂
There is also no other approach that works better or even just as well as this one.
You could use file locking instead. But that would just make everything more complex and yield no additional advantages (besides being more complicated which some people do see as a huge advantage for some reason). And you’d add a lot of nice corner cases when your file is on a network drive.
You could use open(2) with the mode O_CREAT which would make the function fail if the file already exists. But that wouldn’t prevent a second process to delete the file and writing their own copy.
Or you could create a lock directory since creating directories has to be atomic as well. But that would not buy you much, either. You’d have to write the locking code yourself and make absolutely, 100% sure that you really, really always delete the lock directory in case of disaster – which you can’t.
There is in fact a way to do this, atomically and safely, provided all actors do it the same way. It’s an adaptation of the lock-free whack-a-mole algorithm, and not entirely trivial, so feel free to go with “no” as the general answer 😉
What to do
- Check whether the file already exists. Stop if it does.
- Generate a unique ID
- Copy the source file to the target folder with a temporary name, say,
<target>.<UUID>.tmp.
- Rename†the copy
<target>-<UUID>.mole.tmp.
- Look for any other files matching the pattern
<target>-*.mole.tmp.
- If their UUID compares greater than yours, attempt to delete it. (Don’t worry if it’s gone.)
- If their UUID compares less than yours, attempt to delete your own. (Again, don’t worry if it’s gone.) From now on, treat their UUID as if it were your own.
- Check again to see if the destination file already exists. If so, attempt to delete your temporary file. (Don’t worry if it’s gone. Remember your UUID may have changed in step 5.)
- If you didn’t already attempt to delete it in step 6, attempt to rename your temporary file to its final name,
<target>. (Don’t worry if it’s gone, just jump back to step 5.)
You’re done!
How it works
Imagine each candidate source file is a mole coming out of its hole. Half-way out, it pauses and whacks any competing moles back into the ground, before checking no other mole has fully emerged. If you run this through in your head, you should see that only one mole will ever make it all the way out. To prevent this system from livelocking, we add a total ordering on which mole can whack which. Bam! A PhD thesis lock-free algorithm.
†Step 4 may look unnecessary—why not just use that name in the first place? However, another process may “adopt” your mole file in step 5, and make it the winner in step 7, so it’s very important that you’re not still writing out the contents! Renames on the same file system are atomic, so step 4 is safe.
A while back my team needed a mechanism for atomic writes in Python and we came up the following code (also available in a gist):
def copy_with_metadata(source, target):
"""Copy file with all its permissions and metadata.
Lifted from https://stackoverflow.com/a/43761127/2860309
:param source: source file name
:param target: target file name
"""
# copy content, stat-info (mode too), timestamps...
shutil.copy2(source, target)
# copy owner and group
st = os.stat(source)
os.chown(target, st[stat.ST_UID], st[stat.ST_GID])
def atomic_write(file_contents, target_file_path, mode="w"):
"""Write to a temporary file and rename it to avoid file corruption.
Attribution: @therightstuff, @deichrenner, @hrudham
:param file_contents: contents to be written to file
:param target_file_path: the file to be created or replaced
:param mode: the file mode defaults to "w", only "w" and "a" are supported
"""
# Use the same directory as the destination file so that moving it across
# file systems does not pose a problem.
temp_file = tempfile.NamedTemporaryFile(
delete=False,
dir=os.path.dirname(target_file_path))
try:
# preserve file metadata if it already exists
if os.path.exists(target_file_path):
copy_with_metadata(target_file_path, temp_file.name)
with open(temp_file.name, mode) as f:
f.write(file_contents)
f.flush()
os.fsync(f.fileno())
os.replace(temp_file.name, target_file_path)
finally:
if os.path.exists(temp_file.name):
try:
os.unlink(temp_file.name)
except:
pass
With this code, copying a file atomically is as simple as reading it into a variable and then sending it to atomic_write.
The comments should provide a good idea of what’s going on but I also wrote up this more complete explanation on Medium for anyone interested.
I need to copy a file from one location to another, and I need to throw an exception (or at least somehow recognise) if the file already exists at the destination (no overwriting).
I can check first with os.path.exists() but it’s extremely important that the file cannot be created in the small amount of time between checking and copying.
Is there a built-in way of doing this, or is there a way to define an action as atomic?
There is no way to do this; file copy operations are never atomic and there is no way to make them.
But you can write the file under a random, temporary name and then rename it. Rename operations have to be atomic. If the file already exists, the rename will fail and you’ll get an error.
[EDIT2] rename() is only atomic if you do it in the same file system. The safe way is to create the new file in the same folder as the destination.
[EDIT] There is a lot of discussion whether rename is always atomic or not and about the overwrite behavior. So I dug up some resources.
On Linux, if the destination exists and both source and destination are files, then the destination is silently overwritten (man page). So I was wrong there.
But rename(2) still guarantees that either the original file or the new file remain valid if something goes wrong, so the operation is atomic in the sense that it can’t corrupt data. It’s not atomic in the sense that it prevents two processes from doing the same rename at the same time and you can predict the result. One will win but you can’t tell which.
On Windows, if another process is currently writing the file, you get an error if you try to open it for writing, so one advantage for Windows, here.
If your computer crashes while the operation is written to disk, the implementation of the file system will decide how much data gets corrupted. There is nothing an application could do about this. So stop whining already 🙂
There is also no other approach that works better or even just as well as this one.
You could use file locking instead. But that would just make everything more complex and yield no additional advantages (besides being more complicated which some people do see as a huge advantage for some reason). And you’d add a lot of nice corner cases when your file is on a network drive.
You could use open(2) with the mode O_CREAT which would make the function fail if the file already exists. But that wouldn’t prevent a second process to delete the file and writing their own copy.
Or you could create a lock directory since creating directories has to be atomic as well. But that would not buy you much, either. You’d have to write the locking code yourself and make absolutely, 100% sure that you really, really always delete the lock directory in case of disaster – which you can’t.
There is in fact a way to do this, atomically and safely, provided all actors do it the same way. It’s an adaptation of the lock-free whack-a-mole algorithm, and not entirely trivial, so feel free to go with “no” as the general answer 😉
What to do
- Check whether the file already exists. Stop if it does.
- Generate a unique ID
- Copy the source file to the target folder with a temporary name, say,
<target>.<UUID>.tmp. - Rename†the copy
<target>-<UUID>.mole.tmp. - Look for any other files matching the pattern
<target>-*.mole.tmp.- If their UUID compares greater than yours, attempt to delete it. (Don’t worry if it’s gone.)
- If their UUID compares less than yours, attempt to delete your own. (Again, don’t worry if it’s gone.) From now on, treat their UUID as if it were your own.
- Check again to see if the destination file already exists. If so, attempt to delete your temporary file. (Don’t worry if it’s gone. Remember your UUID may have changed in step 5.)
- If you didn’t already attempt to delete it in step 6, attempt to rename your temporary file to its final name,
<target>. (Don’t worry if it’s gone, just jump back to step 5.)
You’re done!
How it works
Imagine each candidate source file is a mole coming out of its hole. Half-way out, it pauses and whacks any competing moles back into the ground, before checking no other mole has fully emerged. If you run this through in your head, you should see that only one mole will ever make it all the way out. To prevent this system from livelocking, we add a total ordering on which mole can whack which. Bam! A PhD thesis lock-free algorithm.
†Step 4 may look unnecessary—why not just use that name in the first place? However, another process may “adopt” your mole file in step 5, and make it the winner in step 7, so it’s very important that you’re not still writing out the contents! Renames on the same file system are atomic, so step 4 is safe.
A while back my team needed a mechanism for atomic writes in Python and we came up the following code (also available in a gist):
def copy_with_metadata(source, target):
"""Copy file with all its permissions and metadata.
Lifted from https://stackoverflow.com/a/43761127/2860309
:param source: source file name
:param target: target file name
"""
# copy content, stat-info (mode too), timestamps...
shutil.copy2(source, target)
# copy owner and group
st = os.stat(source)
os.chown(target, st[stat.ST_UID], st[stat.ST_GID])
def atomic_write(file_contents, target_file_path, mode="w"):
"""Write to a temporary file and rename it to avoid file corruption.
Attribution: @therightstuff, @deichrenner, @hrudham
:param file_contents: contents to be written to file
:param target_file_path: the file to be created or replaced
:param mode: the file mode defaults to "w", only "w" and "a" are supported
"""
# Use the same directory as the destination file so that moving it across
# file systems does not pose a problem.
temp_file = tempfile.NamedTemporaryFile(
delete=False,
dir=os.path.dirname(target_file_path))
try:
# preserve file metadata if it already exists
if os.path.exists(target_file_path):
copy_with_metadata(target_file_path, temp_file.name)
with open(temp_file.name, mode) as f:
f.write(file_contents)
f.flush()
os.fsync(f.fileno())
os.replace(temp_file.name, target_file_path)
finally:
if os.path.exists(temp_file.name):
try:
os.unlink(temp_file.name)
except:
pass
With this code, copying a file atomically is as simple as reading it into a variable and then sending it to atomic_write.
The comments should provide a good idea of what’s going on but I also wrote up this more complete explanation on Medium for anyone interested.