shutil— High-level file operations

Source code:Lib/shutil.py

---

Theshutilmodule offers a number of high-level operations on files and collections of files. In particular, functions are provided which support file copying and removal. For operations on individual files, see also the osmodule.

Warning

Even the higher-level file copying functions (shutil.copy(), shutil.copy2()) cannot copy all file metadata.

On POSIX platforms, this means that file owner and group are lost as well as ACLs. On Mac OS, the resource fork and other metadata are not used. This means that resources will be lost and file type and creator codes will not be correct. On Windows, file owners, ACLs and alternate data streams are not copied.

Directory and files operations

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

Copy the contents of thefile-like objectfsrcto the file-like objectfdst. The integerlength,if given, is the buffer size. In particular, a negative lengthvalue means to copy the data without looping over the source data in chunks; by default the data is read in chunks to avoid uncontrolled memory consumption. Note that if the current file position of thefsrcobject is not 0, only the contents from the current file position to the end of the file will be copied.

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

Copy the contents (no metadata) of the file namedsrcto a file named dstand returndstin the most efficient way possible. srcanddstarepath-like objectsor path names given as strings.

dstmust be the complete target file name; look atcopy() for a copy that accepts a target directory path. Ifsrcanddst specify the same file,SameFileErroris raised.

The destination location must be writable; otherwise, anOSError exception will be raised. Ifdstalready exists, it will be replaced. Special files such as character or block devices and pipes cannot be copied with this function.

Iffollow_symlinksis false andsrcis a symbolic link, a new symbolic link will be created instead of copying the filesrcpoints to.

Raises anauditing eventshutil.copyfilewith argumentssrc,dst.

Changed in version 3.3:IOErrorused to be raised instead ofOSError. Addedfollow_symlinksargument. Now returnsdst.

Changed in version 3.4:RaiseSameFileErrorinstead ofError.Since the former is a 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 to copy the file more efficiently. See Platform-dependent efficient copy operationssection.

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 fromsrctodst.The file contents, owner, and group are unaffected.srcanddstarepath-like objectsor path names given as strings. Iffollow_symlinksis false, and bothsrcanddstare symbolic links, copymode()will attempt to modify the mode ofdstitself (rather than the file it points to). This functionality is not available on every platform; please seecopystat()for more information. If copymode()cannot modify symbolic links on the local platform, and it is asked to do so, it will do nothing and return.

Raises anauditing eventshutil.copymodewith argumentssrc,dst.

Changed in version 3.3:Addedfollow_symlinksargument.

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

Copy the permission bits, last access time, last modification time, and flags fromsrctodst.On Linux,copystat()also copies the “extended attributes” where possible. The file contents, owner, and group are unaffected.srcanddstarepath-like objectsor path names given as strings.

Iffollow_symlinksis false, andsrcanddstboth refer to symbolic links,copystat()will operate on the symbolic links themselves rather than the files the symbolic links refer to—reading the information from the srcsymbolic link, and writing the information to the dstsymbolic link.

Note

Not all platforms provide the ability to examine and modify symbolic links. Python itself can tell you what functionality is locally available.

• Ifos.chmodinos.supports_follow_symlinksis True,copystat()can modify the permission bits of a symbolic link.

• Ifos.utimeinos.supports_follow_symlinksis True,copystat()can modify the last access and modification times of a symbolic link.

• Ifos.chflagsinos.supports_follow_symlinksis True,copystat()can modify the flags of a symbolic link. (os.chflagsis not available on all platforms.)

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

Please seeos.supports_follow_symlinks for more information.

Raises anauditing eventshutil.copystatwith argumentssrc,dst.

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

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

Copies the filesrcto the file or directorydst.srcanddst should bepath-like objectsor strings. If dstspecifies a directory, the file will be copied intodstusing the base filename fromsrc.Ifdstspecifies a file that already exists, it will be replaced. Returns the path to the newly created file.

Iffollow_symlinksis false, andsrcis a symbolic link, dstwill be created as a symbolic link. Iffollow_symlinks is true andsrcis a symbolic link,dstwill be a copy of the filesrcrefers to.

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

Raises anauditing eventshutil.copyfilewith argumentssrc,dst.

Raises anauditing eventshutil.copymodewith argumentssrc,dst.

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

Changed in version 3.8:Platform-specific fast-copy syscalls may be used internally in order to copy the file more efficiently. See Platform-dependent efficient copy operationssection.

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

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

Whenfollow_symlinksis false, andsrcis a symbolic link,copy2()attempts to copy all metadata from the srcsymbolic link to the newly createddstsymbolic link. However, this functionality is not available on all platforms. On platforms where some or all of this functionality is unavailable,copy2()will preserve all the metadata it can;copy2()never raises an exception because it cannot preserve file metadata.

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

Raises anauditing eventshutil.copyfilewith argumentssrc,dst.

Raises anauditing eventshutil.copystatwith argumentssrc,dst.

Changed in version 3.3:Addedfollow_symlinksargument, try to copy extended file 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 to copy the file more efficiently. See Platform-dependent efficient copy operationssection.

shutil.ignore_patterns(*patterns)

This factory function creates a function that can be used as a callable for copytree()'signoreargument, ignoring files and directories that match one of the glob-stylepatternsprovided. 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 atsrcto a directory nameddstand return the destination directory. All intermediate directories needed to containdstwill also be created by default.

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

Ifsymlinksis true, symbolic links in the source tree are represented as symbolic links in the new tree and the metadata of the original links will be copied as far as the platform allows; if false or omitted, the contents and metadata of the linked files are copied to the new tree.

Whensymlinksis false, if the file pointed to by the symlink doesn’t exist, an exception will be added in the list of errors raised in anErrorexception at the end of the copy process. You can set the optionalignore_dangling_symlinksflag to true if you want to silence this exception. Notice that this option has no effect on platforms that don’t supportos.symlink().

Ifignoreis given, it must be a callable that will receive as its arguments the directory being visited bycopytree(),and a list of its contents, as returned byos.listdir().Sincecopytree()is called recursively, theignorecallable will be called once for each directory that is copied. The callable must return a sequence of directory and file names relative to the current directory (i.e. a subset of the items in its second argument); these names will then be ignored in the copy process.ignore_patterns()can be used to create such a callable that ignores names based on glob-style patterns.

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

Ifcopy_functionis given, it must be a callable that will be used to copy each file. It will be called with the source path and the destination path as arguments. By default,copy2()is used, but any function that supports the same signature (likecopy()) can be used.

Ifdirs_exist_okis false (the default) anddstalready exists, a FileExistsErroris raised. Ifdirs_exist_okis true, the copying operation will continue if it encounters existing directories, and files within thedsttree will be overwritten by corresponding files from the srctree.

Raises anauditing eventshutil.copytreewith argumentssrc,dst.

Changed in version 3.2:Added thecopy_functionargument to be able to provide a custom copy function. Added theignore_dangling_symlinksargument to silence dangling symlinks errors whensymlinksis false.

Changed in version 3.3:Copy metadata whensymlinksis false. Now returnsdst.

Changed in version 3.8:Platform-specific fast-copy syscalls may be used internally in order to copy the file more efficiently. See Platform-dependent efficient copy operationssection.

Changed in version 3.8:Added thedirs_exist_okparameter.

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

Delete an entire directory tree;pathmust point to a directory (but not a symbolic link to a directory). Ifignore_errorsis true, errors resulting from failed removals will be ignored; if false or omitted, such errors are handled by calling a handler specified byonexcoronerroror, if both are 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 symlink attack resistant version ofrmtree()is used by default. On other platforms, thermtree()implementation is susceptible to a symlink attack: given proper timing and circumstances, attackers can manipulate symlinks on the filesystem to delete files they wouldn’t be able to access otherwise. Applications can use thermtree.avoids_symlink_attacks function attribute to determine which case applies.

Ifonexcis 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 byonexc will not be caught.

The deprecatedonerroris similar toonexc,except that the third parameter it receives is the tuple returned fromsys.exc_info().

Raises anauditing eventshutil.rmtreewith argumentspath,dir_fd.

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

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

Changed in version 3.11:Added thedir_fdparameter.

Changed in version 3.12:Added theonexcparameter, deprecatedonerror.

Changed in version 3.13:rmtree()now ignoresFileNotFoundErrorexceptions for all but the top-level path. Exceptions other thanOSErrorand subclasses ofOSError are now always propagated to the caller.

rmtree.avoids_symlink_attacks

Indicates whether the current platform and implementation provides a symlink attack resistant version ofrmtree().Currently this is only 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 return the destination.

Ifdstis an existing directory or a symlink to a directory, thensrc is moved inside that directory. The destination path in that directory must not already exist.

Ifdstalready exists but is not a directory, it may be overwritten depending onos.rename()semantics.

If the destination is on the current filesystem, thenos.rename()is used. Otherwise,srcis copied to the destination usingcopy_function and then removed. In case of symlinks, a new symlink pointing to the target ofsrcwill be created as the destination andsrcwill be removed.

Ifcopy_functionis given, it must be a callable that takes two arguments, srcand the destination, and will be used to copysrcto the destination ifos.rename()cannot be used. If the source is a directory, copytree()is called, passing it thecopy_function.The defaultcopy_functioniscopy2().Usingcopy()as the copy_functionallows the move to succeed when it is not possible to also copy the metadata, at the expense of not copying any of the metadata.

Raises anauditing eventshutil.movewith argumentssrc,dst.

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

Changed in version 3.5:Added thecopy_functionkeyword argument.

Changed in version 3.8:Platform-specific fast-copy syscalls may be used internally in order to copy the file more efficiently. See Platform-dependent efficient copy operationssection.

Changed in version 3.9:Accepts apath-like objectfor bothsrcanddst.

shutil.disk_usage(path)

Return disk usage statistics about the given path as anamed tuple with the attributestotal,usedandfree,which are the amount of total, used and free space, in bytes.pathmay be a file or a directory.

Note

On Unix filesystems,pathmust point to a path within amounted filesystem partition. On those platforms, CPython doesn’t attempt to retrieve disk usage information from non-mounted filesystems.

Added in version 3.3.

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

Availability:Unix, Windows.

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

Change owneruserand/orgroupof the givenpath.

usercan be a system user name or a uid; the same applies togroup.At least one argument is required.

See alsoos.chown(),the underlying function.

Raises anauditing eventshutil.chownwith argumentspath,user,group.

Availability:Unix.

Added in version 3.3.

Changed in version 3.13:Addeddir_fdandfollow_symlinksparameters.

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

Return the path to an executable which would be run if the givencmdwas called. If nocmdwould be called, returnNone.

modeis a permission mask passed toos.access(),by default determining if the file exists and is executable.

pathis a “PATHstring” specifying the directories to look in, delimited byos.pathsep.When nopathis specified, the PATHenvironment variable is read fromos.environ, falling back toos.defpathif it is not set.

On Windows, the current directory is prepended to thepathifmodedoes not includeos.X_OK.When themodedoes includeos.X_OK,the Windows APINeedCurrentDirectoryForExePathWwill be consulted to determine if the current directory should be prepended topath.To avoid consulting the current working directory for executables: set the environment variableNoDefaultCurrentDirectoryInExePath.

Also on Windows, thePATHEXTenvironment variable is used to resolve commands that may not already include an extension. For example, if you callshutil.which( "Python" ),which()will searchPATHEXT to know that it should look forPython.exewithin thepath directories. For example, on Windows:

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

This is also applied whencmdis a path that contains a directory component:

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

Added in version 3.3.

Changed in version 3.8:Thebytestype is now accepted. Ifcmdtype is bytes,the result type is alsobytes.

Changed in version 3.12:On Windows, the current directory is no longer prepended to the search path ifmodeincludesos.X_OKand WinAPI NeedCurrentDirectoryForExePathW(cmd)is false, else the current directory is prepended even if it is already in the search path; PATHEXTis used now even whencmdincludes a directory component or ends with an extension that is inPATHEXT;and filenames that have no extension can now be found.

Changed in version 3.12.1:On Windows, ifmodeincludesos.X_OK,executables with an extension inPATHEXTwill be preferred over executables without a matching extension. This brings behavior closer to that of Python 3.11.

exceptionshutil.Error

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

Platform-dependent efficient copy operations

Starting from Python 3.8, all functions involving a file copy (copyfile(),copy(),copy2(), copytree(),andmove()) may use platform-specific “fast-copy” syscalls in order to copy the file more efficiently (seebpo-33671). “fast-copy” means that the copying operation occurs within the kernel, avoiding the use of userspace buffers in Python as in “outfd.write(infd.read())”.

On macOSfcopyfileis used to copy the file content (not metadata).

On Linuxos.sendfile()is used.

On Windowsshutil.copyfile()uses a bigger default buffer size (1 MiB instead of 64 KiB) and amemoryview()-based variant of shutil.copyfileobj()is used.

If the fast-copy operation fails and no data was written in the destination file then shutil will silently fallback on using less efficient copyfileobj()function internally.

Changed in version 3.8.

copytree example

An example that uses theignore_patterns()helper:

fromshutilimportcopytree,ignore_patterns

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

This will copy everything except.pycfiles and files or directories whose name starts withtmp.

Another example that uses theignoreargument to add a logging call:

fromshutilimportcopytree
importlogging

def_logpath(path,names):
logging.info('Working in%s',path)
return[]# nothing will be ignored

copytree(source,destination,ignore=_logpath)

rmtree example

This example shows how to remove a directory tree on Windows where some of the files have their read-only bit set. It uses the onexc callback to clear the readonly bit and reattempt the remove. Any subsequent failure will propagate.

importos,stat
importshutil

defremove_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

Added in version 3.2.

Changed in version 3.5:Added support for thexztarformat.

High-level utilities to create and read compressed and archived files are also provided. They rely on thezipfileandtarfilemodules.

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_nameis the name of the file to create, including the path, minus any format-specific extension.

formatis the archive format: one of “zip” (if thezlibmodule is available), “tar”, “gztar” (if the zlibmodule is available), “bztar” (if thebz2module is available), or “xztar” (if thelzmamodule is available).

root_diris a directory that will be the root directory of the archive, all paths in the archive will be relative to it; for example, we typically chdir intoroot_dirbefore creating the archive.

base_diris the directory where we start archiving from; i.e.base_dirwill be the common prefix of all files and directories in the archive.base_dirmust be given relative toroot_dir.SeeArchiving example with base_dirfor how to usebase_dirandroot_dirtogether.

root_dirandbase_dirboth default to the current directory.

Ifdry_runis true, no archive is created, but the operations that would be executed are logged tologger.

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

loggermust be an object compatible withPEP 282,usually an instance of logging.Logger.

Theverboseargument is unused and deprecated.

Raises anauditing eventshutil.make_archivewith argumentsbase_name,format,root_dir,base_dir.

Note

This function is not thread-safe when custom archivers registered withregister_archive_format()do not support theroot_dir argument. In this case it temporarily changes the current working directory of the process toroot_dirto perform archiving.

Changed in version 3.8:The modern pax (POSIX.1-2001) format is now used instead of the 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 .zipand 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 defaultshutilprovides these formats:

• zip:ZIP file (if thezlibmodule is available).

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

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

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

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

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

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

Register an archiver for the formatname.

functionis the callable that will be used to unpack archives. The callable will receive thebase_nameof the file to create, followed by the base_dir(which defaults toos.curdir) to start archiving from. Further arguments are passed as keyword arguments:owner,group, dry_runandlogger(as passed inmake_archive()).

Iffunctionhas the custom attributefunction.supports_root_dirset toTrue, theroot_dirargument is passed as a keyword argument. Otherwise the current working directory of the process is temporarily changed toroot_dirbefore callingfunction. In this casemake_archive()is not thread-safe.

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

descriptionis used byget_archive_formats()which returns the list of archivers. Defaults to an empty string.

Changed in version 3.12:Added support for functions supporting theroot_dirargument.

shutil.unregister_archive_format(name)

Remove the archive formatnamefrom the list of supported formats.

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

Unpack an archive.filenameis the full path of the archive.

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

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

The keyword-onlyfilterargument is passed to the underlying unpacking function. For zip files,filteris not accepted. For tar files, it is recommended to set it to'data', unless using features specific to tar and UNIX-like filesystems. (SeeExtraction filtersfor details.) The'data'filter will become the default for tar files in Python 3.14.

Raises anauditing eventshutil.unpack_archivewith 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 in theextract_dirargument, e.g. members that have absolute filenames starting with “/” or filenames with two dots “..”.

Changed in version 3.7:Accepts apath-like objectforfilenameandextract_dir.

Changed in version 3.12:Added thefilterargument.

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

Registers an unpack format.nameis the name of the format and extensionsis a list of extensions corresponding to the format, like .zipfor Zip files.

functionis the callable that will be used to unpack archives. The callable will receive:

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

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

• possibly afilterkeyword argument, if it was given to unpack_archive();

• additional keyword arguments, specified byextra_argsas a sequence of(name,value)tuples.

descriptioncan be provided to describe the format, and will be returned by theget_unpack_formats()function.

shutil.unregister_unpack_format(name)

Unregister an unpack format.nameis 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 defaultshutilprovides these formats:

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

• tar:uncompressed tar file.

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

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

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

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

Archiving example

In this example, we create a gzip’ed tar-file archive containing all files found in the.sshdirectory of the user:

>>>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'

The resulting archive contains:

$tar-tzvf/Users/tarek/myarchive.tar.gz
drwx------ 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

Archiving example withbase_dir

In this example, similar to theone above, we show how to usemake_archive(),but this time with the usage of base_dir.We now have the following directory structure:

$treetmp
tmp
└── root
└── structure
├── content
└── please_add.txt
└── do_not_add.txt

In the final archive,please_add.txtshould be included, but do_not_add.txtshould not. Therefore we use the following:

>>>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'

Listing the files in the resulting archive gives us:

$Python-mtarfile-l/Users/tarek/myarchive.tar
structure/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,COLUMNS andLINESrespectively, is checked. If the variable is defined and the value is a positive integer, it is used.

WhenCOLUMNSorLINESis not defined, which is the common case, the terminal connected tosys.__stdout__is queried by invokingos.get_terminal_size().

If the terminal size cannot be successfully queried, either because the system doesn’t support querying, or because we are not connected to a terminal, the value given infallbackparameter is used.fallbackdefaults to(80,24)which is the default size 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:Thefallbackvalues are also used ifos.get_terminal_size() returns zeroes.