Copy files
Create backups or distribute generated files.
Python · Module
shutil
shutil provides high-level filesystem operations for copying, moving, deleting, and archiving files and directory trees. It complements os by simplifying common multi-file and directory tasks.
How it works
Import shutil when you need high-level operations over files or groups of files. Its functions cover copying, moving, deleting, directory-tree operations, and archive creation; path arguments can generally be strings or path-like objects, while individual-file operations can also be handled with os.
Syntax
import shutilParameters
| Name | Type | Description |
|---|---|---|
src / fsrc / path | path-like object, string path, or file-like object | Source path or source file-like object, depending on the operation. |
dst / fdst | path-like object, string path, or file-like object | Destination path or destination file-like object, depending on the operation. |
follow_symlinks | bool | Whether symlinks should be followed for operations that expose this option. |
ignore_errors | bool | Whether rmtree() should suppress removal errors. |
onerror / onexc | callable | Callbacks used by rmtree() to process removal failures. |
Returns
Return values depend on the operation: file-copy functions generally return the destination path, copytree() returns the destination directory, and removal or archive operations may return None or an archive path as documented.
Key points
- shutil provides high-level utilities for manipulating individual files and collections of files.
- The module includes operations for copying and removing filesystem objects.
- copyfile() transfers file contents without copying metadata.
- copyfile() returns the destination path after the copy succeeds.
- copytree() duplicates a complete directory hierarchy.
- rmtree() removes a directory and everything beneath it.
Common mistakes
- Even copy2() cannot guarantee that every piece of file metadata is preserved.
- rmtree() removes a directory tree, but its path must identify a directory rather than a directory symlink.
- Copy operations fail when the destination cannot be written.
Example: Copy a file with metadata
from pathlib import Path
import shutil
source = Path("source.txt")
target = Path("backup.txt")
source.write_text("important data\n", encoding="utf-8")
shutil.copy2(source, target)
print(target.read_text(encoding="utf-8"))
source.unlink()
target.unlink()Creates a file, copies it while attempting to preserve metadata, reads the copy, and removes both files.
When to use it
Move filesystem content
Relocate files or directories within a filesystem.
Recursive cleanup
Remove temporary directory trees during cleanup.
Archive workflows
Create or extract compressed archives.
Interview questions
QHow do copyfile(), copy(), and copy2() differ?
shutil.copyfile() copies file contents without metadata and requires the destination to be a complete file name. shutil.copy() accepts a file or directory destination and also copies the permission mode.
Follow-up: When should copy2() be preferred? Use it when preserving metadata is useful; it behaves like copy() while additionally attempting to preserve metadata, without guaranteeing every metadata field.
QWhat does copytree() do?
shutil.copytree() recursively copies an entire directory tree rooted at src into dst and returns the destination directory. It is intended for directory trees rather than a single file.
Follow-up: What must be considered when copying a tree containing symlinks? Check the function's symlinks and ignore behavior, because symlink handling is configurable and errors may be aggregated.
QHow does rmtree() handle errors?
shutil.rmtree() deletes an entire directory tree. By default, removal errors are handled through the configured error callback or propagated to the caller if no handler is supplied.
Follow-up: How can failure handling be changed? Set ignore_errors to suppress removal errors, or provide onexc/onerror to handle them explicitly.
Related
osshutil.copyfileshutil.copyshutil.copy2shutil.copytreeshutil.moveshutil.rmtreeshutil.make_archive