Directory and files operations¶

shutil.copyfileobj(fsrc,fdst[,length])¶

Copy the contents of thefile-like objectfsrc to the file-like objectfdst.The integerlength, if given, is the buffer size. In particular, a negativelength value means to copy the data without looping over the source data inchunks; by default the data is read in chunks to avoid uncontrolled memoryconsumption. Note that if the current file position of thefsrc object is not0, only the contents from the current file position to the end of the file willbe copied.

shutil.copyfile(src,dst,*,follow_symlinks=True)¶

Copy the contents (no metadata) of the file namedsrc to a file nameddst and returndst in the most efficient way possible.src anddst arepath-like objects or path names given as strings.

dst must be the complete target file name; look atcopy()for a copy that accepts a target directory path. Ifsrc anddstspecify the same file,SameFileError is raised.

The destination location must be writable; otherwise, anOSErrorexception will be raised. Ifdst already exists, it will be replaced.Special files such as character or block devices and pipes cannot becopied with this function.

Iffollow_symlinks is false andsrc is a symbolic link,a new symbolic link will be created instead of copying thefilesrc points to.

Raises anauditing eventshutil.copyfile with argumentssrc,dst.

Changed in version 3.3:IOError used to be raised instead ofOSError.Addedfollow_symlinks argument.Now returnsdst.

Changed in version 3.4:RaiseSameFileError instead ofError. Since the former isa subclass of the latter, this change is backward compatible.

Changed in version 3.8:Platform-specific fast-copy syscalls may be used internally in order tocopy the file more efficiently. SeePlatform-dependent efficient copy operations section.

exceptionshutil.SameFileError¶

This exception is raised if source and destination incopyfile()are the same file.

Added in version 3.4.

shutil.copymode(src,dst,*,follow_symlinks=True)¶

Copy the permission bits fromsrc todst. The file contents, owner, andgroup are unaffected.src anddst arepath-like objects or path namesgiven as strings.Iffollow_symlinks is false, and bothsrc anddst are symbolic links,copymode() will attempt to modify the mode ofdst itself (ratherthan the file it points to). This functionality is not available on everyplatform; please seecopystat() for more information. Ifcopymode() cannot modify symbolic links on the local platform, and itis asked to do so, it will do nothing and return.

Raises anauditing eventshutil.copymode with argumentssrc,dst.

Changed in version 3.3:Addedfollow_symlinks argument.

shutil.copystat(src,dst,*,follow_symlinks=True)¶

Copy the permission bits, last access time, last modification time, andflags fromsrc todst. On Linux,copystat() also copies the“extended attributes” where possible. The file contents, owner, andgroup are unaffected.src anddst arepath-like objects or pathnames given as strings.

Iffollow_symlinks is false, andsrc anddst bothrefer to symbolic links,copystat() will operate onthe symbolic links themselves rather than the files thesymbolic links refer to—reading the information from thesrc symbolic link, and writing the information to thedst symbolic link.

Note

Not all platforms provide the ability to examine andmodify symbolic links. Python itself can tell you whatfunctionality is locally available.

• Ifos.chmodinos.supports_follow_symlinks isTrue,copystat() can modify the permissionbits of a symbolic link.

• Ifos.utimeinos.supports_follow_symlinks isTrue,copystat() can modify the last accessand modification times of a symbolic link.

• Ifos.chflagsinos.supports_follow_symlinks isTrue,copystat() can modify the flags ofa symbolic link. (os.chflags is not available onall platforms.)

On platforms where some or all of this functionalityis unavailable, when asked to modify a symbolic link,copystat() will copy everything it can.copystat() never returns failure.

Please seeos.supports_follow_symlinksfor more information.

Raises anauditing eventshutil.copystat with argumentssrc,dst.

Changed in version 3.3:Addedfollow_symlinks argument and support for Linux extended attributes.

shutil.copy(src,dst,*,follow_symlinks=True)¶

Copies the filesrc to the file or directorydst.src anddstshould bepath-like objects or strings. Ifdst specifies a directory, the file will be copied intodst using thebase filename fromsrc. Ifdst specifies a file that already exists,it will be replaced. Returns the path to the newly created file.

Iffollow_symlinks is false, andsrc is a symbolic link,dst will be created as a symbolic link. Iffollow_symlinksis true andsrc is a symbolic link,dst will be a copy ofthe filesrc refers to.

copy() copies the file data and the file’s permissionmode (seeos.chmod()). Other metadata, like thefile’s creation and modification times, is not preserved.To preserve all file metadata from the original, usecopy2() instead.

Raises anauditing eventshutil.copyfile with argumentssrc,dst.

Raises anauditing eventshutil.copymode with argumentssrc,dst.

Changed in version 3.3:Addedfollow_symlinks argument.Now returns path to the newly created file.

Changed in version 3.8:Platform-specific fast-copy syscalls may be used internally in order tocopy the file more efficiently. SeePlatform-dependent efficient copy operations section.

shutil.copy2(src,dst,*,follow_symlinks=True)¶

Identical tocopy() except thatcopy2()also attempts to preserve file metadata.

Whenfollow_symlinks is false, andsrc is a symboliclink,copy2() attempts to copy all metadata from thesrc symbolic link to the newly createddst symbolic link.However, this functionality is not available on all platforms.On platforms where some or all of this functionality isunavailable,copy2() will preserve all the metadatait can;copy2() never raises an exception because itcannot preserve file metadata.

copy2() usescopystat() to copy the file metadata.Please seecopystat() for more informationabout platform support for modifying symbolic link metadata.

Raises anauditing eventshutil.copyfile with argumentssrc,dst.

Raises anauditing eventshutil.copystat with argumentssrc,dst.

Changed in version 3.3:Addedfollow_symlinks argument, try to copy extendedfile system attributes too (currently Linux only).Now returns path to the newly created file.

Changed in version 3.8:Platform-specific fast-copy syscalls may be used internally in order tocopy the file more efficiently. SeePlatform-dependent efficient copy operations section.

shutil.ignore_patterns(*patterns)¶

This factory function creates a function that can be used as a callable forcopytree()'signore argument, ignoring files and directories thatmatch one of the glob-stylepatterns provided. See the example below.

shutil.copytree(src,dst,symlinks=False,ignore=None,copy_function=copy2,ignore_dangling_symlinks=False,dirs_exist_ok=False)¶

Recursively copy an entire directory tree rooted atsrc to a directorynameddst and return the destination directory. All intermediatedirectories needed to containdst will also be created by default.

Permissions and times of directories are copied withcopystat(),individual files are copied usingcopy2().

Ifsymlinks is true, symbolic links in the source tree are represented assymbolic links in the new tree and the metadata of the original links willbe copied as far as the platform allows; if false or omitted, the contentsand metadata of the linked files are copied to the new tree.

Whensymlinks is false, if the file pointed to by the symlink doesn’texist, an exception will be added in the list of errors raised inanError exception at the end of the copy process.You can set the optionalignore_dangling_symlinks flag to true if youwant to silence this exception. Notice that this option has no effecton platforms that don’t supportos.symlink().

Ifignore is given, it must be a callable that will receive as itsarguments the directory being visited bycopytree(), and a list of itscontents, as returned byos.listdir(). Sincecopytree() iscalled recursively, theignore callable will be called once for eachdirectory that is copied. The callable must return a sequence of directoryand file names relative to the current directory (i.e. a subset of the itemsin its second argument); these names will then be ignored in the copyprocess.ignore_patterns() can be used to create such a callable thatignores names based on glob-style patterns.

If exception(s) occur, anError is raised with a list of reasons.

Ifcopy_function is given, it must be a callable that will be used to copyeach file. It will be called with the source path and the destination pathas arguments. By default,copy2() is used, but any functionthat supports the same signature (likecopy()) can be used.

Ifdirs_exist_ok is false (the default) anddst already exists, aFileExistsError is raised. Ifdirs_exist_ok is true, the copyingoperation will continue if it encounters existing directories, and fileswithin thedst tree will be overwritten by corresponding files from thesrc tree.

Raises anauditing eventshutil.copytree with argumentssrc,dst.

Changed in version 3.2:Added thecopy_function argument to be able to provide a custom copyfunction.Added theignore_dangling_symlinks argument to silence dangling symlinkserrors whensymlinks is false.

Changed in version 3.3:Copy metadata whensymlinks is false.Now returnsdst.

Changed in version 3.8:Platform-specific fast-copy syscalls may be used internally in order tocopy the file more efficiently. SeePlatform-dependent efficient copy operations section.

Changed in version 3.8:Added thedirs_exist_ok parameter.

shutil.rmtree(path,ignore_errors=False,onerror=None,*,onexc=None,dir_fd=None)¶

Delete an entire directory tree;path must point to a directory (but not asymbolic link to a directory). Ifignore_errors is true, errors resultingfrom failed removals will be ignored; if false or omitted, such errors arehandled by calling a handler specified byonexc oronerror or, if bothare omitted, exceptions are propagated to the caller.

This function can supportpaths relative to directory descriptors.

Note

On platforms that support the necessary fd-based functions a symlinkattack resistant version ofrmtree() is used by default. On otherplatforms, thermtree() implementation is susceptible to a symlinkattack: given proper timing and circumstances, attackers can manipulatesymlinks on the filesystem to delete files they wouldn’t be able to accessotherwise. Applications can use thermtree.avoids_symlink_attacksfunction attribute to determine which case applies.

Ifonexc is provided, it must be a callable that accepts three parameters:function,path, andexcinfo.

The first parameter,function, is the function which raised the exception;it depends on the platform and implementation. The second parameter,path, will be the path name passed tofunction. The third parameter,excinfo, is the exception that was raised. Exceptions raised byonexcwill not be caught.

The deprecatedonerror is similar toonexc, except that the thirdparameter it receives is the tuple returned fromsys.exc_info().

Raises anauditing eventshutil.rmtree with argumentspath,dir_fd.

Changed in version 3.3:Added a symlink attack resistant version that is used automaticallyif platform supports fd-based functions.

Changed in version 3.8:On Windows, will no longer delete the contents of a directory junctionbefore removing the junction.

Changed in version 3.11:Added thedir_fd parameter.

Changed in version 3.12:Added theonexc parameter, deprecatedonerror.

Changed in version 3.13:rmtree() now ignoresFileNotFoundError exceptions for allbut the top-level path.Exceptions other thanOSError and subclasses ofOSErrorare now always propagated to the caller.

rmtree.avoids_symlink_attacks¶

Indicates whether the current platform and implementation provides asymlink attack resistant version ofrmtree(). Currently this isonly true for platforms supporting fd-based directory access functions.

Added in version 3.3.

shutil.move(src,dst,copy_function=copy2)¶

Recursively move a file or directory (src) to another location and returnthe destination.

Ifdst is an existing directory or a symlink to a directory, thensrcis moved inside that directory. The destination path in that directory mustnot already exist.

Ifdst already exists but is not a directory, it may be overwrittendepending onos.rename() semantics.

If the destination is on the current filesystem, thenos.rename() isused. Otherwise,src is copied to the destination usingcopy_functionand then removed. In case of symlinks, a new symlink pointing to the targetofsrc will be created as the destination andsrc will be removed.

Ifcopy_function is given, it must be a callable that takes two arguments,src and the destination, and will be used to copysrc to the destinationifos.rename() cannot be used. If the source is a directory,copytree() is called, passing it thecopy_function. Thedefaultcopy_function iscopy2(). Usingcopy() as thecopy_function allows the move to succeed when it is not possible to alsocopy the metadata, at the expense of not copying any of the metadata.

Raises anauditing eventshutil.move with argumentssrc,dst.

Changed in version 3.3:Added explicit symlink handling for foreign filesystems, thus adaptingit to the behavior of GNU’smv.Now returnsdst.

Changed in version 3.5:Added thecopy_function keyword argument.

Changed in version 3.8:Platform-specific fast-copy syscalls may be used internally in order tocopy the file more efficiently. SeePlatform-dependent efficient copy operations section.

Changed in version 3.9:Accepts apath-like object for bothsrc anddst.

shutil.disk_usage(path)¶

Return disk usage statistics about the given path as anamed tuplewith the attributestotal,used andfree, which are the amount oftotal, used and free space, in bytes.path may be a file or adirectory.

Note

On Unix filesystems,path must point to a path within amountedfilesystem partition. On those platforms, CPython doesn’t attempt toretrieve disk usage information from non-mounted filesystems.

Added in version 3.3.

Changed in version 3.8:On Windows,path can now be a file or directory.

Availability: Unix, Windows.

shutil.chown(path,user=None,group=None,*,dir_fd=None,follow_symlinks=True)¶

Change owneruser and/orgroup of the givenpath.

user can be a system user name or a uid; the same applies togroup. Atleast one argument is required.

See alsoos.chown(), the underlying function.

Raises anauditing eventshutil.chown with argumentspath,user,group.

Availability: Unix.

Added in version 3.3.

Changed in version 3.13:Addeddir_fd andfollow_symlinks parameters.

shutil.which(cmd,mode=os.F_OK|os.X_OK,path=None)¶

Return the path to an executable which would be run if the givencmd wascalled. If nocmd would be called, returnNone.

mode is a permission mask passed toos.access(), by defaultdetermining if the file exists and is executable.

path is a “PATH string” specifying the directories to look in,delimited byos.pathsep. When nopath is specified, thePATH environment variable is read fromos.environ,falling back toos.defpath if it is not set.

Ifcmd contains a directory component,which() only checks thespecified path directly and does not search the directories listed inpath or in the system’sPATH environment variable.

On Windows, the current directory is prepended to thepath ifmode doesnot includeos.X_OK. When themode does includeos.X_OK, theWindows APINeedCurrentDirectoryForExePathW will be consulted todetermine if the current directory should be prepended topath. To avoidconsulting the current working directory for executables: set the environmentvariableNoDefaultCurrentDirectoryInExePath.

Also on Windows, thePATHEXT environment variable is used toresolve commands that may not already include an extension. For example,if you callshutil.which("python"),which() will searchPATHEXTto know that it should look forpython.exe within thepathdirectories. For example, on Windows:

>>>shutil.which("python")'C:\\Python33\\python.EXE'

This is also applied whencmd is a path that contains a directorycomponent:

>>>shutil.which("C:\\Python33\\python")'C:\\Python33\\python.EXE'

Added in version 3.3.

Changed in version 3.8:Thebytes type is now accepted. Ifcmd type isbytes, the result type is alsobytes.

Changed in version 3.12:On Windows, the current directory is no longer prepended to the searchpath ifmode includesos.X_OK and WinAPINeedCurrentDirectoryForExePathW(cmd) is false, else the currentdirectory is prepended even if it is already in the search path;PATHEXT is used now even whencmd includes a directory componentor ends with an extension that is inPATHEXT; and filenames thathave no extension can now be found.

exceptionshutil.Error¶

This exception collects exceptions that are raised during a multi-fileoperation. Forcopytree(), the exception argument is a list of 3-tuples(srcname,dstname,exception).

fromshutilimportcopytree,ignore_patternscopytree(source,destination,ignore=ignore_patterns('*.pyc','tmp*'))

fromshutilimportcopytreeimportloggingdef_logpath(path,names):logging.info('Working in%s',path)return[]# nothing will be ignoredcopytree(source,destination,ignore=_logpath)

importos,statimportshutildefremove_readonly(func,path,_):"Clear the readonly bit and reattempt the removal"os.chmod(path,stat.S_IWRITE)func(path)shutil.rmtree(directory,onexc=remove_readonly)

Archiving operations¶

High-level utilities to create and read compressed and archived files are alsoprovided. They rely on thezipfile andtarfile modules.

shutil.make_archive(base_name,format[,root_dir[,base_dir[,verbose[,dry_run[,owner[,group[,logger]]]]]]])¶

Create an archive file (such as zip or tar) and return its name.

base_name is the name of the file to create, including the path, minusany format-specific extension.

format is the archive format: one of“zip” (if thezlib module is available), “tar”, “gztar” (if thezlib module is available), “bztar” (if thebz2 module isavailable), or “xztar” (if thelzma module is available).

root_dir is a directory that will be the root directory of thearchive, all paths in the archive will be relative to it; for example,we typically chdir intoroot_dir before creating the archive.

base_dir is the directory where we start archiving from;i.e.base_dir will be the common prefix of all files anddirectories in the archive.base_dir must be given relativetoroot_dir. SeeArchiving example with base_dir for how tousebase_dir androot_dir together.

root_dir andbase_dir both default to the current directory.

Ifdry_run is true, no archive is created, but the operations that would beexecuted are logged tologger.

owner andgroup are used when creating a tar archive. By default,uses the current owner and group.

logger must be an object compatible withPEP 282, usually an instance oflogging.Logger.

Theverbose argument is unused and deprecated.

Raises anauditing eventshutil.make_archive with argumentsbase_name,format,root_dir,base_dir.

Note

This function is not thread-safe when custom archivers registeredwithregister_archive_format() do not support theroot_dirargument. In this case ittemporarily changes the current working directory of the processtoroot_dir to perform archiving.

Changed in version 3.8:The modern pax (POSIX.1-2001) format is now used instead ofthe legacy GNU format for archives created withformat="tar".

Changed in version 3.10.6:This function is now made thread-safe during creation of standard.zip and tar archives.

shutil.get_archive_formats()¶

Return a list of supported formats for archiving.Each element of the returned sequence is a tuple(name,description).

By defaultshutil provides these formats:

• zip: ZIP file (if thezlib module is available).

• tar: Uncompressed tar file. Uses POSIX.1-2001 pax format for new archives.

• gztar: gzip’ed tar-file (if thezlib module is available).

• bztar: bzip2’ed tar-file (if thebz2 module is available).

• xztar: xz’ed tar-file (if thelzma module is available).

You can register new formats or provide your own archiver for any existingformats, by usingregister_archive_format().

shutil.register_archive_format(name,function[,extra_args[,description]])¶

Register an archiver for the formatname.

function is the callable that will be used to unpack archives. The callablewill receive thebase_name of the file to create, followed by thebase_dir (which defaults toos.curdir) to start archiving from.Further arguments are passed as keyword arguments:owner,group,dry_run andlogger (as passed inmake_archive()).

Iffunction has the custom attributefunction.supports_root_dir set toTrue,theroot_dir argument is passed as a keyword argument.Otherwise the current working directory of the process is temporarilychanged toroot_dir before callingfunction.In this casemake_archive() is not thread-safe.

If given,extra_args is a sequence of(name,value) pairs that will beused as extra keywords arguments when the archiver callable is used.

description is used byget_archive_formats() which returns thelist of archivers. Defaults to an empty string.

Changed in version 3.12:Added support for functions supporting theroot_dir argument.

shutil.unregister_archive_format(name)¶

Remove the archive formatname from the list of supported formats.

shutil.unpack_archive(filename[,extract_dir[,format[,filter]]])¶

Unpack an archive.filename is the full path of the archive.

extract_dir is the name of the target directory where the archive isunpacked. If not provided, the current working directory is used.

format is the archive format: one of “zip”, “tar”, “gztar”, “bztar”, or“xztar”. Or any other format registered withregister_unpack_format(). If not provided,unpack_archive()will use the archive file name extension and see if an unpacker wasregistered for that extension. In case none is found,aValueError is raised.

The keyword-onlyfilter argument is passed to the underlying unpackingfunction. For zip files,filter is not accepted.For tar files, it is recommended to set it to'data',unless using features specific to tar and UNIX-like filesystems.(SeeExtraction filters for details.)The'data' filter will become the default for tar filesin Python 3.14.

Raises anauditing eventshutil.unpack_archive with argumentsfilename,extract_dir,format.

Warning

Never extract archives from untrusted sources without prior inspection.It is possible that files are created outside of the path specified intheextract_dir argument, e.g. members that have absolute filenamesstarting with “/” or filenames with two dots “..”.

Changed in version 3.7:Accepts apath-like object forfilename andextract_dir.

Changed in version 3.12:Added thefilter argument.

shutil.register_unpack_format(name,extensions,function[,extra_args[,description]])¶

Registers an unpack format.name is the name of the format andextensions is a list of extensions corresponding to the format, like.zip for Zip files.

function is the callable that will be used to unpack archives. Thecallable will receive:

• the path of the archive, as a positional argument;

• the directory the archive must be extracted to, as a positional argument;

• possibly afilter keyword argument, if it was given tounpack_archive();

• additional keyword arguments, specified byextra_args as a sequenceof(name,value) tuples.

description can be provided to describe the format, and will be returnedby theget_unpack_formats() function.

shutil.unregister_unpack_format(name)¶

Unregister an unpack format.name is the name of the format.

shutil.get_unpack_formats()¶

Return a list of all registered formats for unpacking.Each element of the returned sequence is a tuple(name,extensions,description).

By defaultshutil provides these formats:

• zip: ZIP file (unpacking compressed files works only if the correspondingmodule is available).

• tar: uncompressed tar file.

• gztar: gzip’ed tar-file (if thezlib module is available).

• bztar: bzip2’ed tar-file (if thebz2 module is available).

• xztar: xz’ed tar-file (if thelzma module is available).

You can register new formats or provide your own unpacker for any existingformats, by usingregister_unpack_format().

>>>fromshutilimportmake_archive>>>importos>>>archive_name=os.path.expanduser(os.path.join('~','myarchive'))>>>root_dir=os.path.expanduser(os.path.join('~','.ssh'))>>>make_archive(archive_name,'gztar',root_dir)'/Users/tarek/myarchive.tar.gz'

$tar-tzvf/Users/tarek/myarchive.tar.gzdrwx------ tarek/staff       0 2010-02-01 16:23:40 ./-rw-r--r-- tarek/staff     609 2008-06-09 13:26:54 ./authorized_keys-rwxr-xr-x tarek/staff      65 2008-06-09 13:26:54 ./config-rwx------ tarek/staff     668 2008-06-09 13:26:54 ./id_dsa-rwxr-xr-x tarek/staff     609 2008-06-09 13:26:54 ./id_dsa.pub-rw------- tarek/staff    1675 2008-06-09 13:26:54 ./id_rsa-rw-r--r-- tarek/staff     397 2008-06-09 13:26:54 ./id_rsa.pub-rw-r--r-- tarek/staff   37192 2010-02-06 18:23:10 ./known_hosts

$treetmptmp└── root    └── structure        ├── content            └── please_add.txt        └── do_not_add.txt

>>>fromshutilimportmake_archive>>>importos>>>archive_name=os.path.expanduser(os.path.join('~','myarchive'))>>>make_archive(...archive_name,...'tar',...root_dir='tmp/root',...base_dir='structure/content',...)'/Users/tarek/my_archive.tar'

$python-mtarfile-l/Users/tarek/myarchive.tarstructure/content/structure/content/please_add.txt

Querying the size of the output terminal¶

shutil.get_terminal_size(fallback=(columns,lines))¶

Get the size of the terminal window.

For each of the two dimensions, the environment variable,COLUMNSandLINES respectively, is checked. If the variable is defined andthe value is a positive integer, it is used.

WhenCOLUMNS orLINES is not defined, which is the common case,the terminal connected tosys.__stdout__ is queriedby invokingos.get_terminal_size().

If the terminal size cannot be successfully queried, either becausethe system doesn’t support querying, or because we are notconnected to a terminal, the value given infallback parameteris used.fallback defaults to(80,24) which is the defaultsize used by many terminal emulators.

The value returned is a named tuple of typeos.terminal_size.

See also: The Single UNIX Specification, Version 2,Other Environment Variables.

Added in version 3.3.

Changed in version 3.11:Thefallback values are also used ifos.get_terminal_size()returns zeroes.