This page describes the operating system services in Python 3, and how to use them.
Os: Miscellaneous operating system interfaces
The os module provides a portable way of using operating system dependent functionality. If you only want to read or write a file see open(), if you want to manipulate paths, see the os.path module, and if you want to read all the lines in all the files on the command line see the fileinput module. For creating temporary files and directories see the tempfile module, and for high-level file and directory handling see the shutil module.
- The os module
- File descriptor operations
- Files and directories
- Process management
- Python overview
- Linux commands help
Notes on the availability of these functions:
- The design of all built-in operating system dependent modules of Python is such that as long as the same functionality is available, it uses the same interface; for example, the function os.stat(path) returns stat information about path in the same format (which happens to have originated with the POSIX interface).
- Extensions peculiar to a particular operating system are also available through the os module, but using them is of course a threat to portability.
- All functions accepting path or file names accept both bytes and string objects, and result in an object of the same type, if a path or file name is returned.
- An “Availability: Unix” note means that this function is commonly found on Unix systems. It does not make any claims about its existence on a specific operating system.
- If not separately noted, all functions that claim “Availability: Unix” are supported on macOS X, which builds on a Unix core.
Note: All functions in this module raise OSError in the case of invalid or inaccessible file names and paths, or other arguments that have the correct type, but are not accepted by the operating system.
File names, command line arguments, and environment variables
In Python, file names, command line arguments, and environment variables are represented using the string type. On some systems, decoding these strings to and from bytes is necessary before passing them to the operating system. Python uses the file system encoding to perform this conversion (see sys.getfilesystemencoding()).
On some systems, conversion using the file system encoding may fail. In this case, Python uses the surrogateescape encoding error handler, which means that undecodable bytes are replaced by a Unicode character U+DCxx on decoding, and these are again translated to the original byte on encoding.
The file system encoding must guarantee to successfully decode all bytes below 128. If the file system encoding fails to provide this guarantee, API functions may raise UnicodeError.
OS process parameters
These functions and data items provide information and operate on the current process and user.
File object creation
This function creates new file objects. (See also open() for opening file descriptors.)
- sysname - operating system namenodename - name of machine on network (implementation-defined)release - operating system releaseversion - operating system versionmachine - hardware identifier
file descriptor operations
These functions operate on I/O streams referenced using file descriptors.
File descriptors are small integers corresponding to a file that is opened by the current process. For example, standard input is usually file descriptor 0, standard output is 1, and standard error is 2. Further files opened by a process is assigned 3, 4, 5, and so forth. The name “file descriptor” is slightly deceptive; on Unix platforms, sockets and pipes are also referenced by file descriptors.
The fileno() method can be used to obtain the file descriptor associated with a file object when required. Note that using the file descriptor directly will bypass the file object methods, ignoring aspects such as internal buffering of data.
The following constants are options for the flags parameter to the open() function. They can be combined using the bitwise OR operator |. Some of them are not available on all platforms. For descriptions of their availability and use, consult the open() manual page on Unix or the MSDN on Windows.
for fd in range(fd_low, fd_high): try: os.close(fd) except OSError: pass
os.O_RDONLYos.O_WRONLYos.O_RDWRos.O_APPENDos.O_CREATos.O_EXCLos.O_TRUNC
The above constants are available on Unix and Windows.
os.O_DSYNCos.O_RSYNCos.O_SYNCos.O_NDELAYos.O_NONBLOCKos.O_NOCTTYos.O_SHLOCKos.O_EXLOCKos.O_CLOEXEC
The above constants are only available on Unix.
os.O_BINARYos.O_NOINHERITos.O_SHORT_LIVEDos.O_TEMPORARYos.O_RANDOMos.O_SEQUENTIALos.O_TEXT
The above constants are only available on Windows.
os.O_ASYNCos.O_DIRECTos.O_DIRECTORYos.O_NOFOLLOWos.O_NOATIMEos.O_PATHos.O_TMPFILE
The above constants are GNU extensions and not present if they are not defined by the C library.
Querying the size of a terminal
Inheritance of file descriptors
A file descriptor has an “inheritable” flag which indicates if the file descriptor can be inherited by child processes. Since Python 3.4, file descriptors created by Python are non-inheritable by default.
On UNIX, non-inheritable file descriptors are closed in child processes at the execution of a new program, other file descriptors are inherited.
On Windows, non-inheritable handles and file descriptors are closed in child processes, except for standard streams (file descriptors 0, 1 and 2: stdin, stdout and stderr), which are always inherited. Using spawn* functions, all inheritable handles and all inheritable file descriptors are inherited. Using the subprocess module, all file descriptors except standard streams are closed, and inheritable handles are only inherited if the close_fds parameter is False.
Files and directories
On some Unix platforms, many of these functions support one or more of these features:
- specifying a file descriptor: For some functions, the path argument can be not only a string giving a path name, but also a file descriptor. The function will then operate on the file referred to by the descriptor. (For POSIX systems, Python will call the f… version of the function.) You can check whether or not path can be specified as a file descriptor on your platform using os.supports_fd. If it’s unavailable, using it will raise a NotImplementedError. If the function also supports dir_fd or follow_symlinks arguments, it is an error to specify one of those when supplying path as a file descriptor.
- paths relative to directory descriptors: If dir_fd is not None, it should be a file descriptor referring to a directory, and the path to operate on should be relative; path is relative to that directory. If the path is absolute, dir_fd is ignored. (For POSIX systems, Python will call the …at or f…at version of the function.) You can check whether or not dir_fd is supported on your platform using os.supports_dir_fd. If it’s unavailable, using it will raise a NotImplementedError.
- paths relative to directory descriptors: If dir_fd is not None, it should be a file descriptor referring to a directory, and the path to operate on should be relative; path is relative to that directory. If the path is absolute, dir_fd is ignored. (For POSIX systems, Python will call the …at or f…at version of the function.) You can check whether or not dir_fd is supported on your platform using os.supports_dir_fd. If it’s unavailable, using it will raise a NotImplementedError.
- not following symlinks: If follow_symlinks is False, and the last element of the path to operate on is a symbolic link, the function will operate on the symbolic link itself instead of the file the link points to. (For POSIX systems, Python will call the l… version of the function.) You can check whether or not follow_symlinks is supported on your platform using os.supports_follow_symlinks. If it’s unavailable, using it will raise a NotImplementedError.
Linux extended attributes
These functions are all available on Linux only.
if os.access(“myfile”, os.R_OK): with open(“myfile”) as fp: return fp.read()return “some default data”
try: fp = open(“myfile”)except PermissionError: return “some default data"else: with fp: return fp.read()
stat.UF_NODUMPstat.UF_IMMUTABLEstat.UF_APPENDstat.UF_OPAQUEstat.UF_NOUNLINKstat.UF_COMPRESSEDstat.UF_HIDDENstat.SF_ARCHIVEDstat.SF_IMMUTABLEstat.SF_APPENDstat.SF_NOUNLINKstat.SF_SNAPSHOT
stat.S_ISUIDstat.S_ISGIDstat.S_ENFMTstat.S_ISVTXstat.S_IREADstat.S_IWRITEstat.S_IEXECstat.S_IRWXUstat.S_IRUSRstat.S_IWUSRstat.S_IXUSRstat.S_IRWXGstat.S_IRGRPstat.S_IWGRPstat.S_IXGRPstat.S_IRWXOstat.S_IROTHstat.S_IWOTHstat.S_IXOTH
st_mode - protection bits,st_ino - inode number,st_dev - device,st_nlink - number of hard links,st_uid - user id of owner,st_gid - group id of owner,st_size - size of file, in bytes,st_atime - time of most recent access expressed in seconds,st_mtime - time of most recent content modification expressed in seconds,st_ctime - platform dependent; time of most recent metadata change on Unix, or the time of creation on Windows, expressed in secondsst_atime_ns - time of most recent access expressed in nanoseconds as an integer,st_mtime_ns - time of most recent content modification expressed in nanoseconds as an integer,st_ctime_ns - platform dependent; time of most recent metadata change on Unix, or the time of creation on Windows, expressed in nanoseconds as an integer
st_blocks - number of 512-byte blocks allocated for filest_blksize - filesystem blocksize for efficient file system I/Ost_rdev - type of device if an inode devicest_flags - user defined flags for file
st_gen - file generation numberst_birthtime - time of file creation
import os»> statinfo = os.stat(‘somefile.txt’)»> statinfoposix.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
os.stat in os.supports_dir_fd
os.access in os.supports_effective_ids
os.chdir in os.supports_fd
os.stat in os.supports_follow_symlinks
- If ns is not None, it must be a 2-tuple of the form (atime_ns, mtime_ns) where each member is an int expressing nanoseconds.If times is not None, it must be a 2-tuple of the form (atime, mtime) where each member is an int or float expressing seconds.If times and ns are both None, this is equivalent to specifying ns=(atime_ns, mtime_ns) where both times are the current time.
import osfrom os.path import join, getsizefor root, dirs, files in os.walk(‘python/Lib/email’): print(root, “consumes”, end=” “) print(sum(getsize(join(root, name)) for name in files), end=” “) print(“bytes in”, len(files), “non-directory files”) if ‘CVS’ in dirs: dirs.remove(‘CVS’) # don’t visit CVS directories
Delete everything reachable from the directory named in “top”,# assuming there are no symbolic links.# CAUTION: This is dangerous! For example, if top == ‘/’, it# could delete all your disk files.import osfor root, dirs, files in os.walk(top, topdown=False): for name in files: os.remove(os.path.join(root, name)) for name in dirs: os.rmdir(os.path.join(root, name))
import osfor root, dirs, files, rootfd in os.fwalk(‘python/Lib/email’): print(root, “consumes”, end=”") print(sum([os.stat(name, dir_fd=rootfd).st_size for name in files]), end="") print(“bytes in”, len(files), “non-directory files”) if ‘CVS’ in dirs: dirs.remove(‘CVS’) # don’t visit CVS directories
Delete everything reachable from the directory named in “top”,# assuming there are no symbolic links.# CAUTION: This is dangerous! For example, if top == ‘/’, it# could delete all your disk files.import osfor root, dirs, files, rootfd in os.fwalk(top, topdown=False): for name in files: os.unlink(name, dir_fd=rootfd) for name in dirs: os.rmdir(name, dir_fd=rootfd)
Process management
These functions may be used to create and manage processes.
The various exec* functions take a list of arguments for the new program loaded into the process. In each case, the first of these arguments is passed to the new program as its own name rather than as an argument a user may have typed on a command line. For the C programmer, this is the argv[0] passed to a program’s main(). For example, os.execv(’/bin/echo’, [‘foo’, ‘bar’]) only prints bar on standard output; foo will seem to be ignored.
The following exit codes are defined and can be used with _exit(), although they are not required. These are often used for system programs written in Python, such as a mail server’s external command delivery program.
The following functions take a process status code as returned by system(), wait(), or waitpid() as a parameter. They may be used to determine the disposition of a process.
Some of these may not be available on all Unix platforms since there is some variation. These constants are defined where they are defined by the underlying platform.
See ssl for applications that use the SSL module with fork(). Availability: Unix.
import osos.spawnlp(os.P_WAIT, ‘cp’, ‘cp’, ‘index.html’, ‘/dev/null’)L = [‘cp’, ‘index.html’, ‘/dev/null’]os.spawnvpe(os.P_WAIT, ‘cp’, L, os.environ)
- user - user timesystem - system timechildren_user - user time of all child processeschildren_system - system time of all child processeselapsed - elapsed real time since a fixed point in the past
Interface to the scheduler
These functions control how a process is allocated CPU time by the operating system. They are only available on some Unix platforms. For more detailed information, consult your Unix manpages.
The following scheduling policies are exposed if they are supported by the operating system.
Miscellaneous system information
The following data values are used to support path manipulation operations. These are defined for all platforms. Higher-level operations on pathnames are defined in the os.path module.
