File Names, Command Line Arguments, and Environment Variables¶

In Python, file names, command line arguments, and environment variables arerepresented using the string type. On some systems, decoding these strings toand from bytes is necessary before passing them to the operating system. Pythonuses thefilesystem encoding and error handler to perform thisconversion (seesys.getfilesystemencoding()).

Thefilesystem encoding and error handler are configured at Pythonstartup by thePyConfig_Read() function: seefilesystem_encoding andfilesystem_errors members ofPyConfig.

Thefile system encoding mustguarantee to successfully decode all bytes below 128. If the file systemencoding fails to provide this guarantee, API functions can raiseUnicodeError.

See also thelocale encoding.

Python UTF-8 Mode¶

The Python UTF-8 Mode ignores thelocale encoding and forces the usageof the UTF-8 encoding:

• Use UTF-8 as thefilesystem encoding.

• sys.getfilesystemencoding() returns'utf-8'.

• locale.getpreferredencoding() returns'utf-8' (thedo_setlocaleargument has no effect).

• sys.stdin,sys.stdout, andsys.stderr all useUTF-8 as their text encoding, with thesurrogateescapeerror handler being enabled forsys.stdinandsys.stdout (sys.stderr continues to usebackslashreplace as it does in the default locale-aware mode)

• On Unix,os.device_encoding() returns'utf-8' rather than thedevice encoding.

Note that the standard stream settings in UTF-8 mode can be overridden byPYTHONIOENCODING (just as they can be in the default locale-awaremode).

As a consequence of the changes in those lower level APIs, other higherlevel APIs also exhibit different default behaviours:

• Command line arguments, environment variables and filenames are decodedto text using the UTF-8 encoding.

• os.fsdecode() andos.fsencode() use the UTF-8 encoding.

• open(),io.open(), andcodecs.open() use the UTF-8encoding by default. However, they still use the strict error handler bydefault so that attempting to open a binary file in text mode is likelyto raise an exception rather than producing nonsense data.

ThePython UTF-8 Mode is enabled if the LC_CTYPE locale isC orPOSIX at Python startup (see thePyConfig_Read()function).

It can be enabled or disabled using the-Xutf8 command lineoption and thePYTHONUTF8 environment variable.

If thePYTHONUTF8 environment variable is not set at all, then theinterpreter defaults to using the current locale settings,unless the currentlocale is identified as a legacy ASCII-based locale (as described forPYTHONCOERCECLOCALE), and locale coercion is either disabled orfails. In such legacy locales, the interpreter will default to enabling UTF-8mode unless explicitly instructed not to do so.

The Python UTF-8 Mode can only be enabled at the Python startup. Its valuecan be read fromsys.flags.utf8_mode.

See also theUTF-8 mode on Windowsand thefilesystem encoding and error handler.

Process Parameters¶

These functions and data items provide information and operate on the currentprocess and user.

os.ctermid()¶

Return the filename corresponding to the controlling terminal of the process.

Availability: Unix, not WASI.

os.environ¶

Amapping object where keys and values are strings that representthe process environment. For example,environ['HOME'] is the pathnameof your home directory (on some platforms), and is equivalent togetenv("HOME") in C.

This mapping is captured the first time theos module is imported,typically during Python startup as part of processingsite.py. Changesto the environment made after this time are not reflected inos.environ,except for changes made by modifyingos.environ directly.

This mapping may be used to modify the environment as well as query theenvironment.putenv() will be called automatically when the mappingis modified.

On Unix, keys and values usesys.getfilesystemencoding() and'surrogateescape' error handler. Useenvironb if you would liketo use a different encoding.

On Windows, the keys are converted to uppercase. This also applies whengetting, setting, or deleting an item. For example,environ['monty']='python' maps the key'MONTY' to the value'python'.

Note

Callingputenv() directly does not changeos.environ, so it’s betterto modifyos.environ.

Note

On some platforms, including FreeBSD and macOS, settingenviron maycause memory leaks. Refer to the system documentation forputenv().

You can delete items in this mapping to unset environment variables.unsetenv() will be called automatically when an item is deleted fromos.environ, and when one of thepop() orclear() methods iscalled.

Changed in version 3.9:Updated to supportPEP 584’s merge (|) and update (|=) operators.

os.environb¶

Bytes version ofenviron: amapping object where both keysand values arebytes objects representing the process environment.environ andenvironb are synchronized (modifyingenvironb updatesenviron, and vice versa).

environb is only available ifsupports_bytes_environ isTrue.

Added in version 3.2.

Changed in version 3.9:Updated to supportPEP 584’s merge (|) and update (|=) operators.

os.chdir(path)

os.fchdir(fd)

os.getcwd()

These functions are described inFiles and Directories.

os.fsencode(filename)¶

Encodepath-likefilename to thefilesystem encoding and error handler; returnbytesunchanged.

fsdecode() is the reverse function.

Added in version 3.2.

Changed in version 3.6:Support added to accept objects implementing theos.PathLikeinterface.

os.fsdecode(filename)¶

Decode thepath-likefilename from thefilesystem encoding and error handler; returnstrunchanged.

fsencode() is the reverse function.

Added in version 3.2.

Changed in version 3.6:Support added to accept objects implementing theos.PathLikeinterface.

os.fspath(path)¶

Return the file system representation of the path.

Ifstr orbytes is passed in, it is returned unchanged.Otherwise__fspath__() is called and its value isreturned as long as it is astr orbytes object.In all other cases,TypeError is raised.

Added in version 3.6.

classos.PathLike¶

Anabstract base class for objects representing a file system path,e.g.pathlib.PurePath.

Added in version 3.6.

abstractmethod__fspath__()¶

Return the file system path representation of the object.

The method should only return astr orbytes object,with the preference being forstr.

os.getenv(key,default=None)¶

Return the value of the environment variablekey as a string if it exists, ordefault if it doesn’t.key is a string. Note thatsincegetenv() usesos.environ, the mapping ofgetenv() issimilarly also captured on import, and the function may not reflectfuture environment changes.

On Unix, keys and values are decoded withsys.getfilesystemencoding()and'surrogateescape' error handler. Useos.getenvb() if youwould like to use a different encoding.

Availability: Unix, Windows.

os.getenvb(key,default=None)¶

Return the value of the environment variablekey as bytes if it exists, ordefault if it doesn’t.key must be bytes. Note thatsincegetenvb() usesos.environb, the mapping ofgetenvb() issimilarly also captured on import, and the function may not reflectfuture environment changes.

getenvb() is only available ifsupports_bytes_environisTrue.

Availability: Unix.

Added in version 3.2.

os.get_exec_path(env=None)¶

Returns the list of directories that will be searched for a namedexecutable, similar to a shell, when launching a process.env, when specified, should be an environment variable dictionaryto lookup the PATH in.By default, whenenv isNone,environ is used.

Added in version 3.2.

os.getegid()¶

Return the effective group id of the current process. This corresponds to the“set id” bit on the file being executed in the current process.

Availability: Unix, not WASI.

os.geteuid()¶

Return the current process’s effective user id.

Availability: Unix, not WASI.

os.getgid()¶

Return the real group id of the current process.

Availability: Unix.

The function is a stub on WASI, seeWebAssembly platforms for moreinformation.

os.getgrouplist(user,group,/)¶

Return list of group ids thatuser belongs to. Ifgroup is not in thelist, it is included; typically,group is specified as the group IDfield from the password record foruser, because that group ID willotherwise be potentially omitted.

Availability: Unix, not WASI.

Added in version 3.3.

os.getgroups()¶

Return list of supplemental group ids associated with the current process.

Availability: Unix, not WASI.

Note

On macOS,getgroups() behavior differs somewhat fromother Unix platforms. If the Python interpreter was built with adeployment target of10.5 or earlier,getgroups() returnsthe list of effective group ids associated with the current user process;this list is limited to a system-defined number of entries, typically 16,and may be modified by calls tosetgroups() if suitably privileged.If built with a deployment target greater than10.5,getgroups() returns the current group access list for the userassociated with the effective user id of the process; the group accesslist may change over the lifetime of the process, it is not affected bycalls tosetgroups(), and its length is not limited to 16. Thedeployment target value,MACOSX_DEPLOYMENT_TARGET, can beobtained withsysconfig.get_config_var().

os.getlogin()¶

Return the name of the user logged in on the controlling terminal of theprocess. For most purposes, it is more useful to usegetpass.getuser() since the latter checks the environment variablesLOGNAME orUSERNAME to find out who the user is, andfalls back topwd.getpwuid(os.getuid())[0] to get the login name of thecurrent real user id.

Availability: Unix, Windows, not WASI.

os.getpgid(pid)¶

Return the process group id of the process with process idpid. Ifpid is 0,the process group id of the current process is returned.

Availability: Unix, not WASI.

os.getpgrp()¶

Return the id of the current process group.

Availability: Unix, not WASI.

os.getpid()¶

Return the current process id.

The function is a stub on WASI, seeWebAssembly platforms for moreinformation.

os.getppid()¶

Return the parent’s process id. When the parent process has exited, on Unixthe id returned is the one of the init process (1), on Windows it is stillthe same id, which may be already reused by another process.

Availability: Unix, Windows, not WASI.

Changed in version 3.2:Added support for Windows.

os.getpriority(which,who)¶

Get program scheduling priority. The valuewhich is one ofPRIO_PROCESS,PRIO_PGRP, orPRIO_USER, andwhois interpreted relative towhich (a process identifier forPRIO_PROCESS, process group identifier forPRIO_PGRP, and auser ID forPRIO_USER). A zero value forwho denotes(respectively) the calling process, the process group of the calling process,or the real user ID of the calling process.

Availability: Unix, not WASI.

Added in version 3.3.

os.PRIO_PROCESS¶

os.PRIO_PGRP¶

os.PRIO_USER¶

Parameters for thegetpriority() andsetpriority() functions.

Availability: Unix, not WASI.

Added in version 3.3.

os.PRIO_DARWIN_THREAD¶

os.PRIO_DARWIN_PROCESS¶

os.PRIO_DARWIN_BG¶

os.PRIO_DARWIN_NONUI¶

Parameters for thegetpriority() andsetpriority() functions.

Availability: macOS

Added in version 3.12.

os.getresuid()¶

Return a tuple (ruid, euid, suid) denoting the current process’sreal, effective, and saved user ids.

Availability: Unix, not WASI.

Added in version 3.2.

os.getresgid()¶

Return a tuple (rgid, egid, sgid) denoting the current process’sreal, effective, and saved group ids.

Availability: Unix, not WASI.

Added in version 3.2.

os.getuid()¶

Return the current process’s real user id.

Availability: Unix.

The function is a stub on WASI, seeWebAssembly platforms for moreinformation.

os.initgroups(username,gid,/)¶

Call the system initgroups() to initialize the group access list with all ofthe groups of which the specified username is a member, plus the specifiedgroup id.

Availability: Unix, not WASI, not Android.

Added in version 3.2.

os.putenv(key,value,/)¶

Set the environment variable namedkey to the stringvalue. Suchchanges to the environment affect subprocesses started withos.system(),popen() orfork() andexecv().

Assignments to items inos.environ are automatically translated intocorresponding calls toputenv(); however, calls toputenv()don’t updateos.environ, so it is actually preferable to assign to itemsofos.environ. This also applies togetenv() andgetenvb(), whichrespectively useos.environ andos.environb in their implementations.

Note

On some platforms, including FreeBSD and macOS, settingenviron maycause memory leaks. Refer to the system documentation forputenv().

Raises anauditing eventos.putenv with argumentskey,value.

Changed in version 3.9:The function is now always available.

os.setegid(egid,/)¶

Set the current process’s effective group id.

Availability: Unix, not WASI, not Android.

os.seteuid(euid,/)¶

Set the current process’s effective user id.

Availability: Unix, not WASI, not Android.

os.setgid(gid,/)¶

Set the current process’ group id.

Availability: Unix, not WASI, not Android.

os.setgroups(groups,/)¶

Set the list of supplemental group ids associated with the current process togroups.groups must be a sequence, and each element must be an integeridentifying a group. This operation is typically available only to the superuser.

Availability: Unix, not WASI.

Note

On macOS, the length ofgroups may not exceed thesystem-defined maximum number of effective group ids, typically 16.See the documentation forgetgroups() for cases where it may notreturn the same group list set by calling setgroups().

os.setns(fd,nstype=0)¶

Reassociate the current thread with a Linux namespace.See thesetns(2) andnamespaces(7) man pages for moredetails.

Iffd refers to a/proc/pid/ns/ link,setns() reassociates thecalling thread with the namespace associated with that link,andnstype may be set to one of theCLONE_NEW* constantsto impose constraints on the operation(0 means no constraints).

Since Linux 5.8,fd may refer to a PID file descriptor obtained frompidfd_open(). In this case,setns() reassociates the calling threadinto one or more of the same namespaces as the thread referred to byfd.This is subject to any constraints imposed bynstype,which is a bit mask combining one or more of theCLONE_NEW* constants,e.g.setns(fd,os.CLONE_NEWUTS|os.CLONE_NEWPID).The caller’s memberships in unspecified namespaces are left unchanged.

fd can be any object with afileno() method, or a raw file descriptor.

This example reassociates the thread with theinit process’s network namespace:

fd=os.open("/proc/1/ns/net",os.O_RDONLY)os.setns(fd,os.CLONE_NEWNET)os.close(fd)

Availability: Linux >= 3.0 with glibc >= 2.14.

Added in version 3.12.

See also

Theunshare() function.

os.setpgrp()¶

Call the system callsetpgrp() orsetpgrp(0,0) depending onwhich version is implemented (if any). See the Unix manual for the semantics.

Availability: Unix, not WASI.

os.setpgid(pid,pgrp,/)¶

Call the system callsetpgid() to set the process group id of theprocess with idpid to the process group with idpgrp. See the Unix manualfor the semantics.

Availability: Unix, not WASI.

os.setpriority(which,who,priority)¶

Set program scheduling priority. The valuewhich is one ofPRIO_PROCESS,PRIO_PGRP, orPRIO_USER, andwhois interpreted relative towhich (a process identifier forPRIO_PROCESS, process group identifier forPRIO_PGRP, and auser ID forPRIO_USER). A zero value forwho denotes(respectively) the calling process, the process group of the calling process,or the real user ID of the calling process.priority is a value in the range -20 to 19. The default priority is 0;lower priorities cause more favorable scheduling.

Availability: Unix, not WASI.

Added in version 3.3.

os.setregid(rgid,egid,/)¶

Set the current process’s real and effective group ids.

Availability: Unix, not WASI, not Android.

os.setresgid(rgid,egid,sgid,/)¶

Set the current process’s real, effective, and saved group ids.

Availability: Unix, not WASI, not Android.

Added in version 3.2.

os.setresuid(ruid,euid,suid,/)¶

Set the current process’s real, effective, and saved user ids.

Availability: Unix, not WASI, not Android.

Added in version 3.2.

os.setreuid(ruid,euid,/)¶

Set the current process’s real and effective user ids.

Availability: Unix, not WASI, not Android.

os.getsid(pid,/)¶

Call the system callgetsid(). See the Unix manual for the semantics.

Availability: Unix, not WASI.

os.setsid()¶

Call the system callsetsid(). See the Unix manual for the semantics.

Availability: Unix, not WASI.

os.setuid(uid,/)¶

Set the current process’s user id.

Availability: Unix, not WASI, not Android.

os.strerror(code,/)¶

Return the error message corresponding to the error code incode.On platforms wherestrerror() returnsNULL when given an unknownerror number,ValueError is raised.

os.supports_bytes_environ¶

True if the native OS type of the environment is bytes (eg.False onWindows).

Added in version 3.2.

os.umask(mask,/)¶

Set the current numeric umask and return the previous umask.

The function is a stub on WASI, seeWebAssembly platforms for moreinformation.

os.uname()¶

Returns information identifying the current operating system.The return value is an object with five attributes:

• sysname - operating system name

• nodename - name of machine on network (implementation-defined)

• release - operating system release

• version - operating system version

• machine - hardware identifier

For backwards compatibility, this object is also iterable, behavinglike a five-tuple containingsysname,nodename,release,version, andmachinein that order.

Some systems truncatenodename to 8 characters or to theleading component; a better way to get the hostname issocket.gethostname() or evensocket.gethostbyaddr(socket.gethostname()).

On macOS, iOS and Android, this returns thekernel name and version (i.e.,'Darwin' on macOS and iOS;'Linux' on Android).platform.uname()can be used to get the user-facing operating system name and version on iOS andAndroid.

Availability: Unix.

Changed in version 3.3:Return type changed from a tuple to a tuple-like objectwith named attributes.

os.unsetenv(key,/)¶

Unset (delete) the environment variable namedkey. Such changes to theenvironment affect subprocesses started withos.system(),popen() orfork() andexecv().

Deletion of items inos.environ is automatically translated into acorresponding call tounsetenv(); however, calls tounsetenv()don’t updateos.environ, so it is actually preferable to delete items ofos.environ.

Raises anauditing eventos.unsetenv with argumentkey.

Changed in version 3.9:The function is now always available and is also available on Windows.

os.unshare(flags)¶

Disassociate parts of the process execution context, and move them into anewly created namespace.See theunshare(2)man page for more details.Theflags argument is a bit mask, combining zero or more of theCLONE_* constants,that specifies which parts of the execution context should beunshared from their existing associations and moved to a new namespace.If theflags argument is0, no changes are made to the calling process’sexecution context.

Availability: Linux >= 2.6.16.

Added in version 3.12.

See also

Thesetns() function.

Flags to theunshare() function, if the implementation supports them.Seeunshare(2) in the Linux manualfor their exact effect and availability.

os.CLONE_FILES¶

os.CLONE_FS¶

os.CLONE_NEWCGROUP¶

os.CLONE_NEWIPC¶

os.CLONE_NEWNET¶

os.CLONE_NEWNS¶

os.CLONE_NEWPID¶

os.CLONE_NEWTIME¶

os.CLONE_NEWUSER¶

os.CLONE_NEWUTS¶

os.CLONE_SIGHAND¶

os.CLONE_SYSVSEM¶

os.CLONE_THREAD¶

os.CLONE_VM¶

File Object Creation¶

These functions create newfile objects. (See alsoopen() for opening file descriptors.)

os.fdopen(fd,*args,**kwargs)¶

Return an open file object connected to the file descriptorfd. This is analias of theopen() built-in function and accepts the same arguments.The only difference is that the first argument offdopen() must alwaysbe an integer.

File Descriptor Operations¶

These functions operate on I/O streams referenced using file descriptors.

File descriptors are small integers corresponding to a file that has been openedby the current process. For example, standard input is usually file descriptor0, standard output is 1, and standard error is 2. Further files opened by aprocess will then be assigned 3, 4, 5, and so forth. The name “file descriptor”is slightly deceptive; on Unix platforms, sockets and pipes are also referencedby file descriptors.

Thefileno() method can be used to obtain the file descriptorassociated with afile object when required. Note that using the filedescriptor directly will bypass the file object methods, ignoring aspects suchas internal buffering of data.

os.close(fd)¶

Close file descriptorfd.

Note

This function is intended for low-level I/O and must be applied to a filedescriptor as returned byos.open() orpipe(). To close a “fileobject” returned by the built-in functionopen() or bypopen() orfdopen(), use itsclose() method.

os.closerange(fd_low,fd_high,/)¶

Close all file descriptors fromfd_low (inclusive) tofd_high (exclusive),ignoring errors. Equivalent to (but much faster than):

forfdinrange(fd_low,fd_high):try:os.close(fd)exceptOSError:pass

os.copy_file_range(src,dst,count,offset_src=None,offset_dst=None)¶

Copycount bytes from file descriptorsrc, starting from offsetoffset_src, to file descriptordst, starting from offsetoffset_dst.Ifoffset_src isNone, thensrc is read from the current position;respectively foroffset_dst.

In Linux kernel older than 5.3, the files pointed to bysrc anddstmust reside in the same filesystem, otherwise anOSError israised witherrno set toerrno.EXDEV.

This copy is done without the additional cost of transferring datafrom the kernel to user space and then back into the kernel. Additionally,some filesystems could implement extra optimizations, such as the use ofreflinks (i.e., two or more inodes that share pointers to the samecopy-on-write disk blocks; supported file systems include btrfs and XFS)and server-side copy (in the case of NFS).

The function copies bytes between two file descriptors. Text options, likethe encoding and the line ending, are ignored.

The return value is the amount of bytes copied. This could be less than theamount requested.

Note

On Linux,os.copy_file_range() should not be used for copying arange of a pseudo file from a special filesystem like procfs and sysfs.It will always copy no bytes and return 0 as if the file was emptybecause of a known Linux kernel issue.

Availability: Linux >= 4.5 with glibc >= 2.27.

Added in version 3.8.

os.device_encoding(fd)¶

Return a string describing the encoding of the device associated withfdif it is connected to a terminal; else returnNone.

On Unix, if thePython UTF-8 Mode is enabled, return'UTF-8' rather than the device encoding.

Changed in version 3.10:On Unix, the function now implements the Python UTF-8 Mode.

os.dup(fd,/)¶

Return a duplicate of file descriptorfd. The new file descriptor isnon-inheritable.

On Windows, when duplicating a standard stream (0: stdin, 1: stdout,2: stderr), the new file descriptor isinheritable.

Availability: not WASI.

Changed in version 3.4:The new file descriptor is now non-inheritable.

os.dup2(fd,fd2,inheritable=True)¶

Duplicate file descriptorfd tofd2, closing the latter first ifnecessary. Returnfd2. The new file descriptor isinheritable by default or non-inheritable ifinheritableisFalse.

Availability: not WASI.

Changed in version 3.4:Add the optionalinheritable parameter.

Changed in version 3.7:Returnfd2 on success. Previously,None was always returned.

os.fchmod(fd,mode)¶

Change the mode of the file given byfd to the numericmode. See thedocs forchmod() for possible values ofmode. As of Python 3.3, thisis equivalent toos.chmod(fd,mode).

Raises anauditing eventos.chmod with argumentspath,mode,dir_fd.

Availability: Unix, Windows.

The function is limited on WASI, seeWebAssembly platforms for moreinformation.

Changed in version 3.13:Added support on Windows.

os.fchown(fd,uid,gid)¶

Change the owner and group id of the file given byfd to the numericuidandgid. To leave one of the ids unchanged, set it to -1. Seechown(). As of Python 3.3, this is equivalent toos.chown(fd,uid,gid).

Raises anauditing eventos.chown with argumentspath,uid,gid,dir_fd.

Availability: Unix.

The function is limited on WASI, seeWebAssembly platforms for moreinformation.

os.fdatasync(fd)¶

Force write of file with filedescriptorfd to disk. Does not force update ofmetadata.

Availability: Unix.

Note

This function is not available on MacOS.

os.fpathconf(fd,name,/)¶

Return system configuration information relevant to an open file.namespecifies the configuration value to retrieve; it may be a string which is thename of a defined system value; these names are specified in a number ofstandards (POSIX.1, Unix 95, Unix 98, and others). Some platforms defineadditional names as well. The names known to the host operating system aregiven in thepathconf_names dictionary. For configuration variables notincluded in that mapping, passing an integer forname is also accepted.

Ifname is a string and is not known,ValueError is raised. If aspecific value forname is not supported by the host system, even if it isincluded inpathconf_names, anOSError is raised witherrno.EINVAL for the error number.

As of Python 3.3, this is equivalent toos.pathconf(fd,name).

Availability: Unix.

os.fstat(fd)¶

Get the status of the file descriptorfd. Return astat_resultobject.

As of Python 3.3, this is equivalent toos.stat(fd).

See also

Thestat() function.

os.fstatvfs(fd,/)¶

Return information about the filesystem containing the file associated withfile descriptorfd, likestatvfs(). As of Python 3.3, this isequivalent toos.statvfs(fd).

Availability: Unix.

os.fsync(fd)¶

Force write of file with filedescriptorfd to disk. On Unix, this calls thenativefsync() function; on Windows, the MS_commit() function.

If you’re starting with a buffered Pythonfile objectf, first dof.flush(), and then doos.fsync(f.fileno()), to ensure that all internalbuffers associated withf are written to disk.

Availability: Unix, Windows.

os.ftruncate(fd,length,/)¶

Truncate the file corresponding to file descriptorfd, so that it is atmostlength bytes in size. As of Python 3.3, this is equivalent toos.truncate(fd,length).

Raises anauditing eventos.truncate with argumentsfd,length.

Availability: Unix, Windows.

Changed in version 3.5:Added support for Windows

os.get_blocking(fd,/)¶

Get the blocking mode of the file descriptor:False if theO_NONBLOCK flag is set,True if the flag is cleared.

See alsoset_blocking() andsocket.socket.setblocking().

Availability: Unix, Windows.

The function is limited on WASI, seeWebAssembly platforms for moreinformation.

On Windows, this function is limited to pipes.

Added in version 3.5.

Changed in version 3.12:Added support for pipes on Windows.

os.grantpt(fd,/)¶

Grant access to the slave pseudo-terminal device associated with themaster pseudo-terminal device to which the file descriptorfd refers.The file descriptorfd is not closed upon failure.

Calls the C standard library functiongrantpt().

Availability: Unix, not WASI.

Added in version 3.13.

os.isatty(fd,/)¶

ReturnTrue if the file descriptorfd is open and connected to atty(-like) device, elseFalse.

os.lockf(fd,cmd,len,/)¶

Apply, test or remove a POSIX lock on an open file descriptor.fd is an open file descriptor.cmd specifies the command to use - one ofF_LOCK,F_TLOCK,F_ULOCK orF_TEST.len specifies the section of the file to lock.

Raises anauditing eventos.lockf with argumentsfd,cmd,len.

Availability: Unix.

Added in version 3.3.

os.F_LOCK¶

os.F_TLOCK¶

os.F_ULOCK¶

os.F_TEST¶

Flags that specify what actionlockf() will take.

Availability: Unix.

Added in version 3.3.

os.login_tty(fd,/)¶

Prepare the tty of which fd is a file descriptor for a new login session.Make the calling process a session leader; make the tty the controlling tty,the stdin, the stdout, and the stderr of the calling process; close fd.

Availability: Unix, not WASI.

Added in version 3.11.

os.lseek(fd,pos,whence,/)¶

Set the current position of file descriptorfd to positionpos, modifiedbywhence, and return the new position in bytes relative tothe start of the file.Valid values forwhence are:

• SEEK_SET or0 – setpos relative to the beginning of the file

• SEEK_CUR or1 – setpos relative to the current file position

• SEEK_END or2 – setpos relative to the end of the file

• SEEK_HOLE – setpos to the next data location, relative topos

• SEEK_DATA – setpos to the next data hole, relative topos

Changed in version 3.3:Add support forSEEK_HOLE andSEEK_DATA.

os.SEEK_SET¶

os.SEEK_CUR¶

os.SEEK_END¶

Parameters to thelseek() function and theseek()method onfile-like objects,for whence to adjust the file position indicator.

SEEK_SET

Adjust the file position relative to the beginning of the file.

SEEK_CUR

Adjust the file position relative to the current file position.

SEEK_END

Adjust the file position relative to the end of the file.

Their values are 0, 1, and 2, respectively.

os.SEEK_HOLE¶

os.SEEK_DATA¶

Parameters to thelseek() function and theseek()method onfile-like objects,for seeking file data and holes on sparsely allocated files.

SEEK_DATA

Adjust the file offset to the next location containing data,relative to the seek position.

SEEK_HOLE

Adjust the file offset to the next location containing a hole,relative to the seek position.A hole is defined as a sequence of zeros.

Note

These operations only make sense for filesystems that support them.

Availability: Linux >= 3.1, macOS, Unix

Added in version 3.3.

os.open(path,flags,mode=0o777,*,dir_fd=None)¶

Open the filepath and set various flags according toflags and possiblyits mode according tomode. When computingmode, the current umask valueis first masked out. Return the file descriptor for the newly opened file.The new file descriptor isnon-inheritable.

For a description of the flag and mode values, see the C run-time documentation;flag constants (likeO_RDONLY andO_WRONLY) are defined intheos module. In particular, on Windows addingO_BINARY is needed to open files in binary mode.

This function can supportpaths relative to directory descriptors with thedir_fd parameter.

Raises anauditing eventopen with argumentspath,mode,flags.

Changed in version 3.4:The new file descriptor is now non-inheritable.

Note

This function is intended for low-level I/O. For normal usage, use thebuilt-in functionopen(), which returns afile object withread() andwrite() methods (and many more). Towrap a file descriptor in a file object, usefdopen().

Changed in version 3.3:Added thedir_fd parameter.

Changed in version 3.5:If the system call is interrupted and the signal handler does not raise anexception, the function now retries the system call instead of raising anInterruptedError exception (seePEP 475 for the rationale).

Changed in version 3.6:Accepts apath-like object.

The following constants are options for theflags parameter to theopen() function. They can be combined using the bitwise OR operator|. Some of them are not available on all platforms. For descriptions oftheir availability and use, consult theopen(2) manual page on Unixorthe MSDN on Windows.

os.O_RDONLY¶

os.O_WRONLY¶

os.O_RDWR¶

os.O_APPEND¶

os.O_CREAT¶

os.O_EXCL¶

os.O_TRUNC¶

The above constants are available on Unix and Windows.

os.O_DSYNC¶

os.O_RSYNC¶

os.O_SYNC¶

os.O_NDELAY¶

os.O_NONBLOCK¶

os.O_NOCTTY¶

os.O_CLOEXEC¶

The above constants are only available on Unix.

Changed in version 3.3:AddO_CLOEXEC constant.

os.O_BINARY¶

os.O_NOINHERIT¶

os.O_SHORT_LIVED¶

os.O_TEMPORARY¶

os.O_RANDOM¶

os.O_SEQUENTIAL¶

os.O_TEXT¶

The above constants are only available on Windows.

os.O_EVTONLY¶

os.O_FSYNC¶

os.O_SYMLINK¶

os.O_NOFOLLOW_ANY¶

The above constants are only available on macOS.

Changed in version 3.10:AddO_EVTONLY,O_FSYNC,O_SYMLINKandO_NOFOLLOW_ANY constants.

os.O_ASYNC¶

os.O_DIRECT¶

os.O_DIRECTORY¶

os.O_NOFOLLOW¶

os.O_NOATIME¶

os.O_PATH¶

os.O_TMPFILE¶

os.O_SHLOCK¶

os.O_EXLOCK¶

The above constants are extensions and not present if they are not defined bythe C library.

Changed in version 3.4:AddO_PATH on systems that support it.AddO_TMPFILE, only available on Linux Kernel 3.11 or newer.

os.openpty()¶

Open a new pseudo-terminal pair. Return a pair of file descriptors(master,slave) for the pty and the tty, respectively. The new filedescriptors arenon-inheritable. For a (slightly) moreportable approach, use thepty module.

Availability: Unix, not WASI.

Changed in version 3.4:The new file descriptors are now non-inheritable.

os.pipe()¶

Create a pipe. Return a pair of file descriptors(r,w) usable forreading and writing, respectively. The new file descriptor isnon-inheritable.

Availability: Unix, Windows.

Changed in version 3.4:The new file descriptors are now non-inheritable.

os.pipe2(flags,/)¶

Create a pipe withflags set atomically.flags can be constructed by ORing together one or more of these values:O_NONBLOCK,O_CLOEXEC.Return a pair of file descriptors(r,w) usable for reading and writing,respectively.

Availability: Unix, not WASI.

Added in version 3.3.

os.posix_fallocate(fd,offset,len,/)¶

Ensures that enough disk space is allocated for the file specified byfdstarting fromoffset and continuing forlen bytes.

Availability: Unix.

Added in version 3.3.

os.posix_fadvise(fd,offset,len,advice,/)¶

Announces an intention to access data in a specific pattern thus allowingthe kernel to make optimizations.The advice applies to the region of the file specified byfd starting atoffset and continuing forlen bytes.advice is one ofPOSIX_FADV_NORMAL,POSIX_FADV_SEQUENTIAL,POSIX_FADV_RANDOM,POSIX_FADV_NOREUSE,POSIX_FADV_WILLNEED orPOSIX_FADV_DONTNEED.

Availability: Unix.

Added in version 3.3.

os.POSIX_FADV_NORMAL¶

os.POSIX_FADV_SEQUENTIAL¶

os.POSIX_FADV_RANDOM¶

os.POSIX_FADV_NOREUSE¶

os.POSIX_FADV_WILLNEED¶

os.POSIX_FADV_DONTNEED¶

Flags that can be used inadvice inposix_fadvise() that specifythe access pattern that is likely to be used.

Availability: Unix.

Added in version 3.3.

os.pread(fd,n,offset,/)¶

Read at mostn bytes from file descriptorfd at a position ofoffset,leaving the file offset unchanged.

Return a bytestring containing the bytes read. If the end of the filereferred to byfd has been reached, an empty bytes object is returned.

Availability: Unix.

Added in version 3.3.

os.posix_openpt(oflag,/)¶

Open and return a file descriptor for a master pseudo-terminal device.

Calls the C standard library functionposix_openpt(). Theoflagargument is used to set file status flags and file access modes asspecified in the manual page ofposix_openpt() of your system.

The returned file descriptor isnon-inheritable.If the valueO_CLOEXEC is available on the system, it is added tooflag.

Availability: Unix, not WASI.

Added in version 3.13.

os.preadv(fd,buffers,offset,flags=0,/)¶

Read from a file descriptorfd at a position ofoffset into mutablebytes-like objectsbuffers, leaving the fileoffset unchanged. Transfer data into each buffer until it is full and thenmove on to the next buffer in the sequence to hold the rest of the data.

The flags argument contains a bitwise OR of zero or more of the followingflags:

• RWF_HIPRI

• RWF_NOWAIT

Return the total number of bytes actually read which can be less than thetotal capacity of all the objects.

The operating system may set a limit (sysconf() value'SC_IOV_MAX') on the number of buffers that can be used.

Combine the functionality ofos.readv() andos.pread().

Availability: Linux >= 2.6.30, FreeBSD >= 6.0, OpenBSD >= 2.7, AIX >= 7.1.

Using flags requires Linux >= 4.6.

Added in version 3.7.

os.RWF_NOWAIT¶

Do not wait for data which is not immediately available. If this flag isspecified, the system call will return instantly if it would have to readdata from the backing storage or wait for a lock.

If some data was successfully read, it will return the number of bytes read.If no bytes were read, it will return-1 and set errno toerrno.EAGAIN.

Availability: Linux >= 4.14.

Added in version 3.7.

os.RWF_HIPRI¶

High priority read/write. Allows block-based filesystems to use pollingof the device, which provides lower latency, but may use additionalresources.

Currently, on Linux, this feature is usable only on a file descriptor openedusing theO_DIRECT flag.

Availability: Linux >= 4.6.

Added in version 3.7.

os.ptsname(fd,/)¶

Return the name of the slave pseudo-terminal device associated with themaster pseudo-terminal device to which the file descriptorfd refers.The file descriptorfd is not closed upon failure.

Calls the reentrant C standard library functionptsname_r() ifit is available; otherwise, the C standard library functionptsname(), which is not guaranteed to be thread-safe, is called.

Availability: Unix, not WASI.

Added in version 3.13.

os.pwrite(fd,str,offset,/)¶

Write the bytestring instr to file descriptorfd at position ofoffset, leaving the file offset unchanged.

Return the number of bytes actually written.

Availability: Unix.

Added in version 3.3.

os.pwritev(fd,buffers,offset,flags=0,/)¶

Write thebuffers contents to file descriptorfd at an offsetoffset,leaving the file offset unchanged.buffers must be a sequence ofbytes-like objects. Buffers are processed inarray order. Entire contents of the first buffer is written beforeproceeding to the second, and so on.

The flags argument contains a bitwise OR of zero or more of the followingflags:

• RWF_DSYNC

• RWF_SYNC

• RWF_APPEND

Return the total number of bytes actually written.

The operating system may set a limit (sysconf() value'SC_IOV_MAX') on the number of buffers that can be used.

Combine the functionality ofos.writev() andos.pwrite().

Availability: Linux >= 2.6.30, FreeBSD >= 6.0, OpenBSD >= 2.7, AIX >= 7.1.

Using flags requires Linux >= 4.6.

Added in version 3.7.

os.RWF_DSYNC¶

Provide a per-write equivalent of theO_DSYNCos.open() flag.This flag effect applies only to the data range written by the system call.

Availability: Linux >= 4.7.

Added in version 3.7.

os.RWF_SYNC¶

Provide a per-write equivalent of theO_SYNCos.open() flag.This flag effect applies only to the data range written by the system call.

Availability: Linux >= 4.7.

Added in version 3.7.

os.RWF_APPEND¶

Provide a per-write equivalent of theO_APPENDos.open()flag. This flag is meaningful only foros.pwritev(), and itseffect applies only to the data range written by the system call. Theoffset argument does not affect the write operation; the data is alwaysappended to the end of the file. However, if theoffset argument is-1, the current fileoffset is updated.

Availability: Linux >= 4.16.

Added in version 3.10.

os.read(fd,n,/)¶

Read at mostn bytes from file descriptorfd.

Return a bytestring containing the bytes read. If the end of the filereferred to byfd has been reached, an empty bytes object is returned.

Note

This function is intended for low-level I/O and must be applied to a filedescriptor as returned byos.open() orpipe(). To read a“file object” returned by the built-in functionopen() or bypopen() orfdopen(), orsys.stdin, use itsread() orreadline() methods.

Changed in version 3.5:If the system call is interrupted and the signal handler does not raise anexception, the function now retries the system call instead of raising anInterruptedError exception (seePEP 475 for the rationale).

os.sendfile(out_fd,in_fd,offset,count)¶

os.sendfile(out_fd,in_fd,offset,count,headers=(),trailers=(),flags=0)

Copycount bytes from file descriptorin_fd to file descriptorout_fdstarting atoffset.Return the number of bytes sent. When EOF is reached return0.

The first function notation is supported by all platforms that definesendfile().

On Linux, ifoffset is given asNone, the bytes are read from thecurrent position ofin_fd and the position ofin_fd is updated.

The second case may be used on macOS and FreeBSD whereheaders andtrailers are arbitrary sequences of buffers that are written before andafter the data fromin_fd is written. It returns the same as the first case.

On macOS and FreeBSD, a value of0 forcount specifies to send untilthe end ofin_fd is reached.

All platforms support sockets asout_fd file descriptor, and some platformsallow other types (e.g. regular file, pipe) as well.

Cross-platform applications should not useheaders,trailers andflagsarguments.

Availability: Unix, not WASI.

Note

For a higher-level wrapper ofsendfile(), seesocket.socket.sendfile().

Added in version 3.3.

Changed in version 3.9:Parametersout andin was renamed toout_fd andin_fd.

os.SF_NODISKIO¶

os.SF_MNOWAIT¶

os.SF_SYNC¶

Parameters to thesendfile() function, if the implementation supportsthem.

Availability: Unix, not WASI.

Added in version 3.3.

os.SF_NOCACHE¶

Parameter to thesendfile() function, if the implementation supportsit. The data won’t be cached in the virtual memory and will be freed afterwards.

Availability: Unix, not WASI.

Added in version 3.11.

os.set_blocking(fd,blocking,/)¶

Set the blocking mode of the specified file descriptor. Set theO_NONBLOCK flag if blocking isFalse, clear the flag otherwise.

See alsoget_blocking() andsocket.socket.setblocking().

Availability: Unix, Windows.

The function is limited on WASI, seeWebAssembly platforms for moreinformation.

On Windows, this function is limited to pipes.

Added in version 3.5.

Changed in version 3.12:Added support for pipes on Windows.

os.splice(src,dst,count,offset_src=None,offset_dst=None)¶

Transfercount bytes from file descriptorsrc, starting from offsetoffset_src, to file descriptordst, starting from offsetoffset_dst.At least one of the file descriptors must refer to a pipe. Ifoffset_srcisNone, thensrc is read from the current position; respectively foroffset_dst. The offset associated to the file descriptor that refers to apipe must beNone. The files pointed to bysrc anddst must reside inthe same filesystem, otherwise anOSError is raised witherrno set toerrno.EXDEV.

This copy is done without the additional cost of transferring datafrom the kernel to user space and then back into the kernel. Additionally,some filesystems could implement extra optimizations. The copy is done as ifboth files are opened as binary.

Upon successful completion, returns the number of bytes spliced to or fromthe pipe. A return value of 0 means end of input. Ifsrc refers to apipe, then this means that there was no data to transfer, and it would notmake sense to block because there are no writers connected to the write endof the pipe.

Availability: Linux >= 2.6.17 with glibc >= 2.5

Added in version 3.10.

os.SPLICE_F_MOVE¶

os.SPLICE_F_NONBLOCK¶

os.SPLICE_F_MORE¶

Added in version 3.10.

os.readv(fd,buffers,/)¶

Read from a file descriptorfd into a number of mutablebytes-likeobjectsbuffers. Transfer data into each buffer untilit is full and then move on to the next buffer in the sequence to hold therest of the data.

Return the total number of bytes actually read which can be less than thetotal capacity of all the objects.

The operating system may set a limit (sysconf() value'SC_IOV_MAX') on the number of buffers that can be used.

Availability: Unix.

Added in version 3.3.

os.tcgetpgrp(fd,/)¶

Return the process group associated with the terminal given byfd (an openfile descriptor as returned byos.open()).

Availability: Unix, not WASI.

os.tcsetpgrp(fd,pg,/)¶

Set the process group associated with the terminal given byfd (an open filedescriptor as returned byos.open()) topg.

Availability: Unix, not WASI.

os.ttyname(fd,/)¶

Return a string which specifies the terminal device associated withfile descriptorfd. Iffd is not associated with a terminal device, anexception is raised.

Availability: Unix.

os.unlockpt(fd,/)¶

Unlock the slave pseudo-terminal device associated with the masterpseudo-terminal device to which the file descriptorfd refers.The file descriptorfd is not closed upon failure.

Calls the C standard library functionunlockpt().

Availability: Unix, not WASI.

Added in version 3.13.

os.write(fd,str,/)¶

Write the bytestring instr to file descriptorfd.

Return the number of bytes actually written.

Note

This function is intended for low-level I/O and must be applied to a filedescriptor as returned byos.open() orpipe(). To write a “fileobject” returned by the built-in functionopen() or bypopen() orfdopen(), orsys.stdout orsys.stderr, use itswrite() method.

Changed in version 3.5:If the system call is interrupted and the signal handler does not raise anexception, the function now retries the system call instead of raising anInterruptedError exception (seePEP 475 for the rationale).

os.writev(fd,buffers,/)¶

Write the contents ofbuffers to file descriptorfd.buffers must bea sequence ofbytes-like objects. Buffers areprocessed in array order. Entire contents of the first buffer is writtenbefore proceeding to the second, and so on.

Returns the total number of bytes actually written.

The operating system may set a limit (sysconf() value'SC_IOV_MAX') on the number of buffers that can be used.

Availability: Unix.

Added in version 3.3.

Files and Directories¶

On some Unix platforms, many of these functions support one or more of thesefeatures:

• specifying a file descriptor:Normally thepath argument provided to functions in theos modulemust be a string specifying a file path. However, some functions nowalternatively accept an open file descriptor for theirpath argument.The function will then operate on the file referred to by the descriptor.(For POSIX systems, Python will call the variant of the function prefixedwithf (e.g. callfchdir instead ofchdir).)

  You can check whether or notpath can be specified as a file descriptorfor a particular function on your platform usingos.supports_fd.If this functionality is unavailable, using it will raise aNotImplementedError.

  If the function also supportsdir_fd orfollow_symlinks arguments, it’san error to specify one of those when supplyingpath as a file descriptor.

• paths relative to directory descriptors: Ifdir_fd is notNone, itshould be a file descriptor referring to a directory, and the path to operateon should be relative; path will then be relative to that directory. If thepath is absolute,dir_fd is ignored. (For POSIX systems, Python will callthe variant of the function with anat suffix and possibly prefixed withf (e.g. callfaccessat instead ofaccess).

  You can check whether or notdir_fd is supported for a particular functionon your platform usingos.supports_dir_fd. If it’s unavailable,using it will raise aNotImplementedError.

• not following symlinks: Iffollow_symlinks isFalse, and the last element of the path to operate on is a symbolic link,the function will operate on the symbolic link itself rather than the filepointed to by the link. (For POSIX systems, Python will call thel...variant of the function.)

  You can check whether or notfollow_symlinks is supported for a particularfunction on your platform usingos.supports_follow_symlinks.If it’s unavailable, using it will raise aNotImplementedError.

os.access(path,mode,*,dir_fd=None,effective_ids=False,follow_symlinks=True)¶

Use the real uid/gid to test for access topath. Note that most operationswill use the effective uid/gid, therefore this routine can be used in asuid/sgid environment to test if the invoking user has the specified access topath.mode should beF_OK to test the existence ofpath, or itcan be the inclusive OR of one or more ofR_OK,W_OK, andX_OK to test permissions. ReturnTrue if access is allowed,False if not. See the Unix man pageaccess(2) for moreinformation.

This function can support specifyingpaths relative to directorydescriptors andnot following symlinks.

Ifeffective_ids isTrue,access() will perform its accesschecks using the effective uid/gid instead of the real uid/gid.effective_ids may not be supported on your platform; you can check whetheror not it is available usingos.supports_effective_ids. If it isunavailable, using it will raise aNotImplementedError.

Note

Usingaccess() to check if a user is authorized to e.g. open a filebefore actually doing so usingopen() creates a security hole,because the user might exploit the short time interval between checkingand opening the file to manipulate it. It’s preferable to useEAFPtechniques. For example:

ifos.access("myfile",os.R_OK):withopen("myfile")asfp:returnfp.read()return"some default data"

is better written as:

try:fp=open("myfile")exceptPermissionError:return"some default data"else:withfp:returnfp.read()

Note

I/O operations may fail even whenaccess() indicates that they wouldsucceed, particularly for operations on network filesystems which may havepermissions semantics beyond the usual POSIX permission-bit model.

Changed in version 3.3:Added thedir_fd,effective_ids, andfollow_symlinks parameters.

Changed in version 3.6:Accepts apath-like object.

os.F_OK¶

os.R_OK¶

os.W_OK¶

os.X_OK¶

Values to pass as themode parameter ofaccess() to test theexistence, readability, writability and executability ofpath,respectively.

os.chdir(path)¶

Change the current working directory topath.

This function can supportspecifying a file descriptor. Thedescriptor must refer to an opened directory, not an open file.

This function can raiseOSError and subclasses such asFileNotFoundError,PermissionError, andNotADirectoryError.

Raises anauditing eventos.chdir with argumentpath.

Changed in version 3.3:Added support for specifyingpath as a file descriptoron some platforms.

Changed in version 3.6:Accepts apath-like object.

os.chflags(path,flags,*,follow_symlinks=True)¶

Set the flags ofpath to the numericflags.flags may take a combination(bitwise OR) of the following values (as defined in thestat module):

• stat.UF_NODUMP

• stat.UF_IMMUTABLE

• stat.UF_APPEND

• stat.UF_OPAQUE

• stat.UF_NOUNLINK

• stat.UF_COMPRESSED

• stat.UF_HIDDEN

• stat.SF_ARCHIVED

• stat.SF_IMMUTABLE

• stat.SF_APPEND

• stat.SF_NOUNLINK

• stat.SF_SNAPSHOT

This function can supportnot following symlinks.

Raises anauditing eventos.chflags with argumentspath,flags.

Availability: Unix, not WASI.

Changed in version 3.3:Added thefollow_symlinks parameter.

Changed in version 3.6:Accepts apath-like object.

os.chmod(path,mode,*,dir_fd=None,follow_symlinks=True)¶

Change the mode ofpath to the numericmode.mode may take one of thefollowing values (as defined in thestat module) or bitwise ORedcombinations of them:

• stat.S_ISUID

• stat.S_ISGID

• stat.S_ENFMT

• stat.S_ISVTX

• stat.S_IREAD

• stat.S_IWRITE

• stat.S_IEXEC

• stat.S_IRWXU

• stat.S_IRUSR

• stat.S_IWUSR

• stat.S_IXUSR

• stat.S_IRWXG

• stat.S_IRGRP

• stat.S_IWGRP

• stat.S_IXGRP

• stat.S_IRWXO

• stat.S_IROTH

• stat.S_IWOTH

• stat.S_IXOTH

This function can supportspecifying a file descriptor,paths relative to directory descriptors andnotfollowing symlinks.

Note

Although Windows supportschmod(), you can only set the file’sread-only flag with it (via thestat.S_IWRITE andstat.S_IREADconstants or a corresponding integer value). All other bits are ignored.The default value offollow_symlinks isFalse on Windows.

The function is limited on WASI, seeWebAssembly platforms for moreinformation.

Raises anauditing eventos.chmod with argumentspath,mode,dir_fd.

Changed in version 3.3:Added support for specifyingpath as an open file descriptor,and thedir_fd andfollow_symlinks arguments.

Changed in version 3.6:Accepts apath-like object.

Changed in version 3.13:Added support for a file descriptor and thefollow_symlinks argumenton Windows.

os.chown(path,uid,gid,*,dir_fd=None,follow_symlinks=True)¶

Change the owner and group id ofpath to the numericuid andgid. Toleave one of the ids unchanged, set it to -1.

This function can supportspecifying a file descriptor,paths relative to directory descriptors andnotfollowing symlinks.

Seeshutil.chown() for a higher-level function that accepts names inaddition to numeric ids.

Raises anauditing eventos.chown with argumentspath,uid,gid,dir_fd.

Availability: Unix.

The function is limited on WASI, seeWebAssembly platforms for moreinformation.

Changed in version 3.3:Added support for specifyingpath as an open file descriptor,and thedir_fd andfollow_symlinks arguments.

Changed in version 3.6:Supports apath-like object.

os.chroot(path)¶

Change the root directory of the current process topath.

Availability: Unix, not WASI, not Android.

Changed in version 3.6:Accepts apath-like object.

os.fchdir(fd)¶

Change the current working directory to the directory represented by the filedescriptorfd. The descriptor must refer to an opened directory, not anopen file. As of Python 3.3, this is equivalent toos.chdir(fd).

Raises anauditing eventos.chdir with argumentpath.

Availability: Unix.

os.getcwd()¶

Return a string representing the current working directory.

os.getcwdb()¶

Return a bytestring representing the current working directory.

Changed in version 3.8:The function now uses the UTF-8 encoding on Windows, rather than the ANSIcode page: seePEP 529 for the rationale. The function is no longerdeprecated on Windows.

os.lchflags(path,flags)¶

Set the flags ofpath to the numericflags, likechflags(), but donot follow symbolic links. As of Python 3.3, this is equivalent toos.chflags(path,flags,follow_symlinks=False).

Raises anauditing eventos.chflags with argumentspath,flags.

Availability: Unix, not WASI.

Changed in version 3.6:Accepts apath-like object.

os.lchmod(path,mode)¶

Change the mode ofpath to the numericmode. If path is a symlink, thisaffects the symlink rather than the target. See the docs forchmod()for possible values ofmode. As of Python 3.3, this is equivalent toos.chmod(path,mode,follow_symlinks=False).

lchmod() is not part of POSIX, but Unix implementations may have it ifchanging the mode of symbolic links is supported.

Raises anauditing eventos.chmod with argumentspath,mode,dir_fd.

Availability: Unix, Windows, not Linux, FreeBSD >= 1.3, NetBSD >= 1.3, not OpenBSD

Changed in version 3.6:Accepts apath-like object.

Changed in version 3.13:Added support on Windows.

os.lchown(path,uid,gid)¶

Change the owner and group id ofpath to the numericuid andgid. Thisfunction will not follow symbolic links. As of Python 3.3, this is equivalenttoos.chown(path,uid,gid,follow_symlinks=False).

Raises anauditing eventos.chown with argumentspath,uid,gid,dir_fd.

Availability: Unix.

Changed in version 3.6:Accepts apath-like object.

os.link(src,dst,*,src_dir_fd=None,dst_dir_fd=None,follow_symlinks=True)¶

Create a hard link pointing tosrc nameddst.

This function can support specifyingsrc_dir_fd and/ordst_dir_fd tosupplypaths relative to directory descriptors, andnotfollowing symlinks.

Raises anauditing eventos.link with argumentssrc,dst,src_dir_fd,dst_dir_fd.

Availability: Unix, Windows.

Changed in version 3.2:Added Windows support.

Changed in version 3.3:Added thesrc_dir_fd,dst_dir_fd, andfollow_symlinks parameters.

Changed in version 3.6:Accepts apath-like object forsrc anddst.

os.listdir(path='.')¶

Return a list containing the names of the entries in the directory given bypath. The list is in arbitrary order, and does not include the specialentries'.' and'..' even if they are present in the directory.If a file is removed from or added to the directory during the call ofthis function, whether a name for that file be included is unspecified.

path may be apath-like object. Ifpath is of typebytes(directly or indirectly through thePathLike interface),the filenames returned will also be of typebytes;in all other circumstances, they will be of typestr.

This function can also supportspecifying a file descriptor; the file descriptor must refer to a directory.

Raises anauditing eventos.listdir with argumentpath.

Note

To encodestr filenames tobytes, usefsencode().

See also

Thescandir() function returns directory entries along withfile attribute information, giving better performance for manycommon use cases.

Changed in version 3.2:Thepath parameter became optional.

Changed in version 3.3:Added support for specifyingpath as an open file descriptor.

Changed in version 3.6:Accepts apath-like object.

os.listdrives()¶

Return a list containing the names of drives on a Windows system.

A drive name typically looks like'C:\\'. Not every drive namewill be associated with a volume, and some may be inaccessible fora variety of reasons, including permissions, network connectivityor missing media. This function does not test for access.

May raiseOSError if an error occurs collecting the drivenames.

Raises anauditing eventos.listdrives with no arguments.

Availability: Windows

Added in version 3.12.

os.listmounts(volume)¶

Return a list containing the mount points for a volume on a Windowssystem.

volume must be represented as a GUID path, like those returned byos.listvolumes(). Volumes may be mounted in multiple locationsor not at all. In the latter case, the list will be empty. Mountpoints that are not associated with a volume will not be returned bythis function.

The mount points return by this function will be absolute paths, andmay be longer than the drive name.

RaisesOSError if the volume is not recognized or if an erroroccurs collecting the paths.

Raises anauditing eventos.listmounts with argumentvolume.

Availability: Windows

Added in version 3.12.

os.listvolumes()¶

Return a list containing the volumes in the system.

Volumes are typically represented as a GUID path that looks like\\?\Volume{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}\. Files canusually be accessed through a GUID path, permissions allowing.However, users are generally not familiar with them, and so therecommended use of this function is to retrieve mount pointsusingos.listmounts().

May raiseOSError if an error occurs collecting the volumes.

Raises anauditing eventos.listvolumes with no arguments.

Availability: Windows

Added in version 3.12.

os.lstat(path,*,dir_fd=None)¶

Perform the equivalent of anlstat() system call on the given path.Similar tostat(), but does not follow symbolic links. Return astat_result object.

On platforms that do not support symbolic links, this is an alias forstat().

As of Python 3.3, this is equivalent toos.stat(path,dir_fd=dir_fd,follow_symlinks=False).

This function can also supportpaths relative to directory descriptors.

See also

Thestat() function.

Changed in version 3.2:Added support for Windows 6.0 (Vista) symbolic links.

Changed in version 3.3:Added thedir_fd parameter.

Changed in version 3.6:Accepts apath-like object.

Changed in version 3.8:On Windows, now opens reparse points that represent another path(name surrogates), including symbolic links and directory junctions.Other kinds of reparse points are resolved by the operating system asforstat().

os.mkdir(path,mode=0o777,*,dir_fd=None)¶

Create a directory namedpath with numeric modemode.

If the directory already exists,FileExistsError is raised. If a parentdirectory in the path does not exist,FileNotFoundError is raised.

On some systems,mode is ignored. Where it is used, the current umaskvalue is first masked out. If bits other than the last 9 (i.e. the last 3digits of the octal representation of themode) are set, their meaning isplatform-dependent. On some platforms, they are ignored and you should callchmod() explicitly to set them.

On Windows, amode of0o700 is specifically handled to apply accesscontrol to the new directory such that only the current user andadministrators have access. Other values ofmode are ignored.

This function can also supportpaths relative to directory descriptors.

It is also possible to create temporary directories; see thetempfile module’stempfile.mkdtemp() function.

Raises anauditing eventos.mkdir with argumentspath,mode,dir_fd.

Changed in version 3.3:Added thedir_fd parameter.

Changed in version 3.6:Accepts apath-like object.

Changed in version 3.13:Windows now handles amode of0o700.

os.makedirs(name,mode=0o777,exist_ok=False)¶

Recursive directory creation function. Likemkdir(), but makes allintermediate-level directories needed to contain the leaf directory.

Themode parameter is passed tomkdir() for creating the leafdirectory; seethe mkdir() description for how itis interpreted. To set the file permission bits of any newly created parentdirectories you can set the umask before invokingmakedirs(). Thefile permission bits of existing parent directories are not changed.

Ifexist_ok isFalse (the default), aFileExistsError israised if the target directory already exists.

Note

makedirs() will become confused if the path elements to createincludepardir (eg. “..” on UNIX systems).

This function handles UNC paths correctly.

Raises anauditing eventos.mkdir with argumentspath,mode,dir_fd.

Changed in version 3.2:Added theexist_ok parameter.

Changed in version 3.4.1:Before Python 3.4.1, ifexist_ok wasTrue and the directory existed,makedirs() would still raise an error ifmode did not match themode of the existing directory. Since this behavior was impossible toimplement safely, it was removed in Python 3.4.1. Seebpo-21082.

Changed in version 3.6:Accepts apath-like object.

Changed in version 3.7:Themode argument no longer affects the file permission bits ofnewly created intermediate-level directories.

os.mkfifo(path,mode=0o666,*,dir_fd=None)¶

Create a FIFO (a named pipe) namedpath with numeric modemode.The current umask value is first masked out from the mode.

This function can also supportpaths relative to directory descriptors.

FIFOs are pipes that can be accessed like regular files. FIFOs exist until theyare deleted (for example withos.unlink()). Generally, FIFOs are used asrendezvous between “client” and “server” type processes: the server opens theFIFO for reading, and the client opens it for writing. Note thatmkfifo()doesn’t open the FIFO — it just creates the rendezvous point.

Availability: Unix, not WASI.

Changed in version 3.3:Added thedir_fd parameter.

Changed in version 3.6:Accepts apath-like object.

os.mknod(path,mode=0o600,device=0,*,dir_fd=None)¶

Create a filesystem node (file, device special file or named pipe) namedpath.mode specifies both the permissions to use and the type of nodeto be created, being combined (bitwise OR) with one ofstat.S_IFREG,stat.S_IFCHR,stat.S_IFBLK, andstat.S_IFIFO (those constants areavailable instat). Forstat.S_IFCHR andstat.S_IFBLK,device defines the newly created device special file (probably usingos.makedev()), otherwise it is ignored.

This function can also supportpaths relative to directory descriptors.

Availability: Unix, not WASI.

Changed in version 3.3:Added thedir_fd parameter.

Changed in version 3.6:Accepts apath-like object.

os.major(device,/)¶

Extract the device major number from a raw device number (usually thest_dev orst_rdev field fromstat).

os.minor(device,/)¶

Extract the device minor number from a raw device number (usually thest_dev orst_rdev field fromstat).

os.makedev(major,minor,/)¶

Compose a raw device number from the major and minor device numbers.

os.pathconf(path,name)¶

Return system configuration information relevant to a named file.namespecifies the configuration value to retrieve; it may be a string which is thename of a defined system value; these names are specified in a number ofstandards (POSIX.1, Unix 95, Unix 98, and others). Some platforms defineadditional names as well. The names known to the host operating system aregiven in thepathconf_names dictionary. For configuration variables notincluded in that mapping, passing an integer forname is also accepted.

Ifname is a string and is not known,ValueError is raised. If aspecific value forname is not supported by the host system, even if it isincluded inpathconf_names, anOSError is raised witherrno.EINVAL for the error number.

This function can supportspecifying a file descriptor.

Availability: Unix.

Changed in version 3.6:Accepts apath-like object.

os.pathconf_names¶

Dictionary mapping names accepted bypathconf() andfpathconf() tothe integer values defined for those names by the host operating system. Thiscan be used to determine the set of names known to the system.

Availability: Unix.

os.readlink(path,*,dir_fd=None)¶

Return a string representing the path to which the symbolic link points. Theresult may be either an absolute or relative pathname; if it is relative, itmay be converted to an absolute pathname usingos.path.join(os.path.dirname(path),result).

If thepath is a string object (directly or indirectly through aPathLike interface), the result will also be a string object,and the call may raise a UnicodeDecodeError. If thepath is a bytesobject (direct or indirectly), the result will be a bytes object.

This function can also supportpaths relative to directory descriptors.

When trying to resolve a path that may contain links, userealpath() to properly handle recursion and platformdifferences.

Availability: Unix, Windows.

Changed in version 3.2:Added support for Windows 6.0 (Vista) symbolic links.

Changed in version 3.3:Added thedir_fd parameter.

Changed in version 3.6:Accepts apath-like object on Unix.

Changed in version 3.8:Accepts apath-like object and a bytes object on Windows.

Added support for directory junctions, and changed to return thesubstitution path (which typically includes\\?\ prefix) ratherthan the optional “print name” field that was previously returned.

os.remove(path,*,dir_fd=None)¶

Remove (delete) the filepath. Ifpath is a directory, anOSError is raised. Usermdir() to remove directories.If the file does not exist, aFileNotFoundError is raised.

This function can supportpaths relative to directory descriptors.

On Windows, attempting to remove a file that is in use causes an exception tobe raised; on Unix, the directory entry is removed but the storage allocatedto the file is not made available until the original file is no longer in use.

This function is semantically identical tounlink().

Raises anauditing eventos.remove with argumentspath,dir_fd.

Changed in version 3.3:Added thedir_fd parameter.

Changed in version 3.6:Accepts apath-like object.

os.removedirs(name)¶

Remove directories recursively. Works likermdir() except that, if theleaf directory is successfully removed,removedirs() tries tosuccessively remove every parent directory mentioned inpath until an erroris raised (which is ignored, because it generally means that a parent directoryis not empty). For example,os.removedirs('foo/bar/baz') will first removethe directory'foo/bar/baz', and then remove'foo/bar' and'foo' ifthey are empty. RaisesOSError if the leaf directory could not besuccessfully removed.

Raises anauditing eventos.remove with argumentspath,dir_fd.

Changed in version 3.6:Accepts apath-like object.

os.rename(src,dst,*,src_dir_fd=None,dst_dir_fd=None)¶

Rename the file or directorysrc todst. Ifdst exists, the operationwill fail with anOSError subclass in a number of cases:

On Windows, ifdst exists aFileExistsError is always raised.The operation may fail ifsrc anddst are on different filesystems. Useshutil.move() to support moves to a different filesystem.

On Unix, ifsrc is a file anddst is a directory or vice-versa, anIsADirectoryError or aNotADirectoryError will be raisedrespectively. If both are directories anddst is empty,dst will besilently replaced. Ifdst is a non-empty directory, anOSErroris raised. If both are files,dst will be replaced silently if the userhas permission. The operation may fail on some Unix flavors ifsrc anddst are on different filesystems. If successful, the renaming will be anatomic operation (this is a POSIX requirement).

This function can support specifyingsrc_dir_fd and/ordst_dir_fd tosupplypaths relative to directory descriptors.

If you want cross-platform overwriting of the destination, usereplace().

Raises anauditing eventos.rename with argumentssrc,dst,src_dir_fd,dst_dir_fd.

Changed in version 3.3:Added thesrc_dir_fd anddst_dir_fd parameters.

Changed in version 3.6:Accepts apath-like object forsrc anddst.

os.renames(old,new)¶

Recursive directory or file renaming function. Works likerename(), exceptcreation of any intermediate directories needed to make the new pathname good isattempted first. After the rename, directories corresponding to rightmost pathsegments of the old name will be pruned away usingremovedirs().

Note

This function can fail with the new directory structure made if you lackpermissions needed to remove the leaf directory or file.

Raises anauditing eventos.rename with argumentssrc,dst,src_dir_fd,dst_dir_fd.

Changed in version 3.6:Accepts apath-like object forold andnew.

os.replace(src,dst,*,src_dir_fd=None,dst_dir_fd=None)¶

Rename the file or directorysrc todst. Ifdst is a non-empty directory,OSError will be raised. Ifdst exists and is a file, it willbe replaced silently if the user has permission. The operation may failifsrc anddst are on different filesystems. If successful,the renaming will be an atomic operation (this is a POSIX requirement).

This function can support specifyingsrc_dir_fd and/ordst_dir_fd tosupplypaths relative to directory descriptors.

Raises anauditing eventos.rename with argumentssrc,dst,src_dir_fd,dst_dir_fd.

Added in version 3.3.

Changed in version 3.6:Accepts apath-like object forsrc anddst.

os.rmdir(path,*,dir_fd=None)¶

Remove (delete) the directorypath. If the directory does not exist or isnot empty, aFileNotFoundError or anOSError is raisedrespectively. In order to remove whole directory trees,shutil.rmtree() can be used.

This function can supportpaths relative to directory descriptors.

Raises anauditing eventos.rmdir with argumentspath,dir_fd.

Changed in version 3.3:Added thedir_fd parameter.

Changed in version 3.6:Accepts apath-like object.

os.scandir(path='.')¶

Return an iterator ofos.DirEntry objects corresponding to theentries in the directory given bypath. The entries are yielded inarbitrary order, and the special entries'.' and'..' are notincluded. If a file is removed from or added to the directory aftercreating the iterator, whether an entry for that file be included isunspecified.

Usingscandir() instead oflistdir() can significantlyincrease the performance of code that also needs file type or fileattribute information, becauseos.DirEntry objects expose thisinformation if the operating system provides it when scanning a directory.Allos.DirEntry methods may perform a system call, butis_dir() andis_file() usually onlyrequire a system call for symbolic links;os.DirEntry.stat()always requires a system call on Unix but only requires one forsymbolic links on Windows.

path may be apath-like object. Ifpath is of typebytes(directly or indirectly through thePathLike interface),the type of thename andpathattributes of eachos.DirEntry will bebytes; in all othercircumstances, they will be of typestr.

This function can also supportspecifying a file descriptor; the file descriptor must refer to a directory.

Raises anauditing eventos.scandir with argumentpath.

Thescandir() iterator supports thecontext manager protocoland has the following method:

scandir.close()¶

Close the iterator and free acquired resources.

This is called automatically when the iterator is exhausted or garbagecollected, or when an error happens during iterating. However itis advisable to call it explicitly or use thewithstatement.

Added in version 3.6.

The following example shows a simple use ofscandir() to display allthe files (excluding directories) in the givenpath that don’t start with'.'. Theentry.is_file() call will generally not make an additionalsystem call:

withos.scandir(path)asit:forentryinit:ifnotentry.name.startswith('.')andentry.is_file():print(entry.name)

Note

On Unix-based systems,scandir() uses the system’sopendir()andreaddir()functions. On Windows, it uses the Win32FindFirstFileWandFindNextFileWfunctions.

Added in version 3.5.

Changed in version 3.6:Added support for thecontext manager protocol and theclose() method. If ascandir() iterator is neitherexhausted nor explicitly closed aResourceWarning will be emittedin its destructor.

The function accepts apath-like object.

Changed in version 3.7:Added support forfile descriptors on Unix.

classos.DirEntry¶

Object yielded byscandir() to expose the file path and other fileattributes of a directory entry.

scandir() will provide as much of this information as possible withoutmaking additional system calls. When astat() orlstat() system callis made, theos.DirEntry object will cache the result.

os.DirEntry instances are not intended to be stored in long-lived datastructures; if you know the file metadata has changed or if a long time haselapsed since callingscandir(), callos.stat(entry.path) to fetchup-to-date information.

Because theos.DirEntry methods can make operating system calls, they mayalso raiseOSError. If you need very fine-grainedcontrol over errors, you can catchOSError when calling one of theos.DirEntry methods and handle as appropriate.

To be directly usable as apath-like object,os.DirEntryimplements thePathLike interface.

Attributes and methods on aos.DirEntry instance are as follows:

name¶

The entry’s base filename, relative to thescandir()pathargument.

Thename attribute will bebytes if thescandir()path argument is of typebytes andstr otherwise. Usefsdecode() to decode byte filenames.

path¶

The entry’s full path name: equivalent toos.path.join(scandir_path,entry.name) wherescandir_path is thescandir()pathargument. The path is only absolute if thescandir()pathargument was absolute. If thescandir()pathargument was afile descriptor, thepathattribute is the same as thename attribute.

Thepath attribute will bebytes if thescandir()path argument is of typebytes andstr otherwise. Usefsdecode() to decode byte filenames.

inode()¶

Return the inode number of the entry.

The result is cached on theos.DirEntry object. Useos.stat(entry.path,follow_symlinks=False).st_ino to fetch up-to-dateinformation.

On the first, uncached call, a system call is required on Windows butnot on Unix.

is_dir(*,follow_symlinks=True)¶

ReturnTrue if this entry is a directory or a symbolic link pointingto a directory; returnFalse if the entry is or points to any otherkind of file, or if it doesn’t exist anymore.

Iffollow_symlinks isFalse, returnTrue only if this entryis a directory (without following symlinks); returnFalse if theentry is any other kind of file or if it doesn’t exist anymore.

The result is cached on theos.DirEntry object, with a separate cacheforfollow_symlinksTrue andFalse. Callos.stat() alongwithstat.S_ISDIR() to fetch up-to-date information.

On the first, uncached call, no system call is required in most cases.Specifically, for non-symlinks, neither Windows or Unix require a systemcall, except on certain Unix file systems, such as network file systems,that returndirent.d_type==DT_UNKNOWN. If the entry is a symlink,a system call will be required to follow the symlink unlessfollow_symlinks isFalse.

This method can raiseOSError, such asPermissionError,butFileNotFoundError is caught and not raised.

is_file(*,follow_symlinks=True)¶

ReturnTrue if this entry is a file or a symbolic link pointing to afile; returnFalse if the entry is or points to a directory or othernon-file entry, or if it doesn’t exist anymore.

Iffollow_symlinks isFalse, returnTrue only if this entryis a file (without following symlinks); returnFalse if the entry isa directory or other non-file entry, or if it doesn’t exist anymore.

The result is cached on theos.DirEntry object. Caching, system callsmade, and exceptions raised are as peris_dir().

is_symlink()¶

ReturnTrue if this entry is a symbolic link (even if broken);returnFalse if the entry points to a directory or any kind of file,or if it doesn’t exist anymore.

The result is cached on theos.DirEntry object. Callos.path.islink() to fetch up-to-date information.

On the first, uncached call, no system call is required in most cases.Specifically, neither Windows or Unix require a system call, except oncertain Unix file systems, such as network file systems, that returndirent.d_type==DT_UNKNOWN.

This method can raiseOSError, such asPermissionError,butFileNotFoundError is caught and not raised.

is_junction()¶

ReturnTrue if this entry is a junction (even if broken);returnFalse if the entry points to a regular directory, any kindof file, a symlink, or if it doesn’t exist anymore.

The result is cached on theos.DirEntry object. Callos.path.isjunction() to fetch up-to-date information.

Added in version 3.12.

stat(*,follow_symlinks=True)¶

Return astat_result object for this entry. This methodfollows symbolic links by default; to stat a symbolic link add thefollow_symlinks=False argument.

On Unix, this method always requires a system call. On Windows, itonly requires a system call iffollow_symlinks isTrue and theentry is a reparse point (for example, a symbolic link or directoryjunction).

On Windows, thest_ino,st_dev andst_nlink attributes of thestat_result are always set to zero. Callos.stat() toget these attributes.

The result is cached on theos.DirEntry object, with a separate cacheforfollow_symlinksTrue andFalse. Callos.stat() tofetch up-to-date information.

Note that there is a nice correspondence between several attributesand methods ofos.DirEntry and ofpathlib.Path. Inparticular, thename attribute has the samemeaning, as do theis_dir(),is_file(),is_symlink(),is_junction(), andstat() methods.

Added in version 3.5.

Changed in version 3.6:Added support for thePathLike interface. Added supportforbytes paths on Windows.

Changed in version 3.12:Thest_ctime attribute of a stat result is deprecated on Windows.The file creation time is properly available asst_birthtime, andin the futurest_ctime may be changed to return zero or themetadata change time, if available.

os.stat(path,*,dir_fd=None,follow_symlinks=True)¶

Get the status of a file or a file descriptor. Perform the equivalent of astat() system call on the given path.path may be specified aseither a string or bytes – directly or indirectly through thePathLikeinterface – or as an open file descriptor. Return astat_resultobject.

This function normally follows symlinks; to stat a symlink add the argumentfollow_symlinks=False, or uselstat().

This function can supportspecifying a file descriptor andnot following symlinks.

On Windows, passingfollow_symlinks=False will disable following allname-surrogate reparse points, which includes symlinks and directoryjunctions. Other types of reparse points that do not resemble links or thatthe operating system is unable to follow will be opened directly. Whenfollowing a chain of multiple links, this may result in the original linkbeing returned instead of the non-link that prevented full traversal. Toobtain stat results for the final path in this case, use theos.path.realpath() function to resolve the path name as far aspossible and calllstat() on the result. This does not apply todangling symlinks or junction points, which will raise the usual exceptions.

Example:

>>>importos>>>statinfo=os.stat('somefile.txt')>>>statinfoos.stat_result(st_mode=33188, st_ino=7876932, st_dev=234881026,st_nlink=1, st_uid=501, st_gid=501, st_size=264, st_atime=1297230295,st_mtime=1297230027, st_ctime=1297230027)>>>statinfo.st_size264

See also

fstat() andlstat() functions.

Changed in version 3.3:Added thedir_fd andfollow_symlinks parameters,specifying a file descriptor instead of a path.

Changed in version 3.6:Accepts apath-like object.

Changed in version 3.8:On Windows, all reparse points that can be resolved by the operatingsystem are now followed, and passingfollow_symlinks=Falsedisables following all name surrogate reparse points. If the operatingsystem reaches a reparse point that it is not able to follow,stat nowreturns the information for the original path as iffollow_symlinks=False had been specified instead of raising an error.

classos.stat_result¶

Object whose attributes correspond roughly to the members of thestat structure. It is used for the result ofos.stat(),os.fstat() andos.lstat().

Attributes:

st_mode¶

File mode: file type and file mode bits (permissions).

st_ino¶

Platform dependent, but if non-zero, uniquely identifies thefile for a given value ofst_dev. Typically:

• the inode number on Unix,

• thefile index onWindows

st_dev¶

Identifier of the device on which this file resides.

st_nlink¶

Number of hard links.

st_uid¶

User identifier of the file owner.

st_gid¶

Group identifier of the file owner.

st_size¶

Size of the file in bytes, if it is a regular file or a symbolic link.The size of a symbolic link is the length of the pathname it contains,without a terminating null byte.

Timestamps:

st_atime¶

Time of most recent access expressed in seconds.

st_mtime¶

Time of most recent content modification expressed in seconds.

st_ctime¶

Time of most recent metadata change expressed in seconds.

Changed in version 3.12:st_ctime is deprecated on Windows. Usest_birthtime forthe file creation time. In the future,st_ctime will containthe time of the most recent metadata change, as for other platforms.

st_atime_ns¶

Time of most recent access expressed in nanoseconds as an integer.

Added in version 3.3.

st_mtime_ns¶

Time of most recent content modification expressed in nanoseconds as aninteger.

Added in version 3.3.

st_ctime_ns¶

Time of most recent metadata change expressed in nanoseconds as aninteger.

Added in version 3.3.

Changed in version 3.12:st_ctime_ns is deprecated on Windows. Usest_birthtime_nsfor the file creation time. In the future,st_ctime will containthe time of the most recent metadata change, as for other platforms.

st_birthtime¶

Time of file creation expressed in seconds. This attribute is notalways available, and may raiseAttributeError.

Changed in version 3.12:st_birthtime is now available on Windows.

st_birthtime_ns¶

Time of file creation expressed in nanoseconds as an integer.This attribute is not always available, and may raiseAttributeError.

Added in version 3.12.

Note

The exact meaning and resolution of thest_atime,st_mtime,st_ctime andst_birthtime attributesdepend on the operating system and the file system. For example, onWindows systems using the FAT32 file systems,st_mtime has2-second resolution, andst_atime has only 1-day resolution.See your operating system documentation for details.

Similarly, althoughst_atime_ns,st_mtime_ns,st_ctime_ns andst_birthtime_ns are always expressed innanoseconds, many systems do not provide nanosecond precision. Onsystems that do provide nanosecond precision, the floating-point objectused to storest_atime,st_mtime,st_ctime andst_birthtime cannot preserve all of it, and as such will beslightly inexact. If you need the exact timestamps you should always usest_atime_ns,st_mtime_ns,st_ctime_ns andst_birthtime_ns.

On some Unix systems (such as Linux), the following attributes may also beavailable:

st_blocks¶

Number of 512-byte blocks allocated for file.This may be smaller thanst_size/512 when the file has holes.

st_blksize¶

“Preferred” blocksize for efficient file system I/O. Writing to a file insmaller chunks may cause an inefficient read-modify-rewrite.

st_rdev¶

Type of device if an inode device.

st_flags¶

User defined flags for file.

On other Unix systems (such as FreeBSD), the following attributes may beavailable (but may be only filled out if root tries to use them):

st_gen¶

File generation number.

On Solaris and derivatives, the following attributes may also beavailable:

st_fstype¶

String that uniquely identifies the type of the filesystem thatcontains the file.

On macOS systems, the following attributes may also be available:

st_rsize¶

Real size of the file.

st_creator¶

Creator of the file.

st_type¶

File type.

On Windows systems, the following attributes are also available:

st_file_attributes¶

Windows file attributes:dwFileAttributes member of theBY_HANDLE_FILE_INFORMATION structure returned byGetFileInformationByHandle().See theFILE_ATTRIBUTE_*<stat.FILE_ATTRIBUTE_ARCHIVE>constants in thestat module.

Added in version 3.5.

st_reparse_tag¶

Whenst_file_attributes has theFILE_ATTRIBUTE_REPARSE_POINTset, this field contains the tag identifying the type of reparse point.See theIO_REPARSE_TAG_*constants in thestat module.

The standard modulestat defines functions and constants that areuseful for extracting information from astat structure. (OnWindows, some items are filled with dummy values.)

For backward compatibility, astat_result instance is alsoaccessible as a tuple of at least 10 integers giving the most important (andportable) members of thestat structure, in the orderst_mode,st_ino,st_dev,st_nlink,st_uid,st_gid,st_size,st_atime,st_mtime,st_ctime. More items may be added at the end bysome implementations. For compatibility with older Python versions,accessingstat_result as a tuple always returns integers.

Changed in version 3.5:Windows now returns the file index asst_ino whenavailable.

Changed in version 3.7:Added thest_fstype member to Solaris/derivatives.

Changed in version 3.8:Added thest_reparse_tag member on Windows.

Changed in version 3.8:On Windows, thest_mode member now identifies specialfiles asS_IFCHR,S_IFIFO orS_IFBLKas appropriate.

Changed in version 3.12:On Windows,st_ctime is deprecated. Eventually, it willcontain the last metadata change time, for consistency with otherplatforms, but for now still contains creation time.Usest_birthtime for the creation time.

On Windows,st_ino may now be up to 128 bits, dependingon the file system. Previously it would not be above 64 bits, andlarger file identifiers would be arbitrarily packed.

On Windows,st_rdev no longer returns a value. Previouslyit would contain the same asst_dev, which was incorrect.

Added thest_birthtime member on Windows.