Skip to content
Tutorials Center
My learning

Topics

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.

Python
import shutil

shutil.copy("report.txt", "backup/report.txt")

Try it

Python Copying, moving and deleting

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.

Python Ignoring files, archives and finding programs

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

  • rmtree is permanent. There is no trash. Print the path before deleting, and never pass a path built from unchecked user input.
  • copy vs. copy2 vs. copyfile. copyfile copies bytes only; copy also copies the permission bits; copy2 adds timestamps. On some platforms not all metadata can be kept.
  • A folder as destination. copy("a.txt", "inbox") places a.txt inside inbox if it exists as a folder; if inbox is not a folder, a file named inbox is written instead.
  • copytree and existing targets. Before Python 3.8 the destination could not exist. Use dirs_exist_ok=True to merge into an existing folder.
  • move can overwrite. Moving onto an existing file may replace it silently on some systems; check first when it matters.
  • Symlinks. copytree follows symbolic links by default and copies the file they point to; pass symlinks=True to 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 filter argument to unpack_archive for 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.