Python Reference ยท Files, Paths and Text I/O
The shutil module
Reference for Python's shutil module: copy, copy2, copytree, move, rmtree, make_archive, disk_usage and which; with examples and safety notes.
shutil ("shell utilities") offers high-level file operations that os does not provide in one call: copying files, copying whole directory trees, moving things between folders, deleting a tree with everything in it, and creating archives.
The functions accept strings or pathlib.Path objects. Deleting and overwriting functions act immediately and cannot be undone, so test with copies first.
import shutil shutil.copy("report.txt", "backup/report.txt")
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.
Most useful functions
| Function | Description |
|---|---|
copyfile(src, dst) |
Copies file contents only. dst must be a full file name. Returns dst. |
copy(src, dst) |
Copies contents and permission bits. dst may be a folder. Returns the new path. |
copy2(src, dst) |
Like copy, and also tries to keep timestamps and other metadata. |
copytree(src, dst, ignore=None, dirs_exist_ok=False) |
Copies a directory tree. By default dst must not exist. |
move(src, dst) |
Moves a file or folder; falls back to copy-then-delete across file systems. Returns the destination. |
rmtree(path, ignore_errors=False) |
Deletes a directory and everything inside it. |
ignore_patterns(*patterns) |
Builds the ignore callback for copytree. |
make_archive(base, format, root_dir) |
Creates zip, tar, gztar, bztar or xztar archives; returns the archive path. |
unpack_archive(file, extract_dir) |
Extracts an archive of a known format. |
disk_usage(path) |
Named tuple (total, used, free) in bytes. |
which(cmd) |
Full path of an executable on PATH, or None. |
Raises: FileNotFoundError, FileExistsError, PermissionError, shutil.SameFileError (copying a file onto itself), shutil.Error (several errors during copytree), shutil.ReadError, ValueError for an unknown archive format.
Usage notes
rmtreeis permanent. There is no trash. Print the path before deleting, and never pass a path built from unchecked user input.copyvs.copy2vs.copyfile.copyfilecopies bytes only;copyalso copies the permission bits;copy2adds timestamps. On some platforms not all metadata can be kept.- A folder as destination.
copy("a.txt", "inbox")placesa.txtinsideinboxif it exists as a folder; ifinboxis not a folder, a file namedinboxis written instead. copytreeand existing targets. Before Python 3.8 the destination could not exist. Usedirs_exist_ok=Trueto merge into an existing folder.movecan overwrite. Moving onto an existing file may replace it silently on some systems; check first when it matters.- Symlinks.
copytreefollows symbolic links by default and copies the file they point to; passsymlinks=Trueto copy the links themselves. - Archive safety. Extracting archives from untrusted sources can write outside the target folder. Inspect member names first; newer Python versions add a
filterargument tounpack_archivefor this purpose. - Large files are copied in chunks, so memory use stays low.
- Alternatives. For one file,
pathlib.Path.write_bytes(src.read_bytes())works but is slower to write and loads everything into memory.
Related
os,os.path,pathlib,tempfile,globandfnmatchzipfileandtarfile- Lessons: os and shutil