1. mirror
  2. cpython


cpython / Doc / library / os.rst

:mod:`os` --- Miscellaneous operating system interfaces

This module provides a portable way of using operating system dependent functionality. If you just want to read or write a file see :func:`open`, if you want to manipulate paths, see the :mod:`os.path` module, and if you want to read all the lines in all the files on the command line see the :mod:`fileinput` module. For creating temporary files and directories see the :mod:`tempfile` module, and for high-level file and directory handling see the :mod:`shutil` module.

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 :mod:`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 Mac OS X, which builds on a Unix core.


All functions in this module raise :exc:`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 :func:`sys.getfilesystemencoding`).

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 UnicodeErrors.

Process Parameters

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

File Object Creation

This function creates new :term:`file objects <file object>`. (See also :func:`~os.open` for opening file descriptors.)

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 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 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 referenced by file descriptors.

The :meth:`~file.fileno` method can be used to obtain the file descriptor associated with a :term:`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 :func:`~os.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 :manpage:`open(2)` manual page on Unix or the MSDN on Windows.

Querying the size of a terminal

A subclass of tuple, holding (columns, lines) of the terminal window size.

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 :func:`os.spawn*` functions, all inheritable handles and all inheritable file descriptors are inherited. Using the :mod:`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 :data:`os.supports_fd`. If it is unavailable, using it will raise a :exc:`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 will then be 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 :data:`os.supports_dir_fd`. If it is unavailable, using it will raise a :exc:`NotImplementedError`.

Linux extended attributes

These functions are all available on Linux only.

Process Management

These functions may be used to create and manage processes.

The various :func:`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 :c:func:`main`. For example, os.execv('/bin/echo', ['foo', 'bar']) will only print bar on standard output; foo will seem to be ignored.

The following exit codes are defined and can be used with :func:`_exit`, although they are not required. These are typically used for system programs written in Python, such as a mail server's external command delivery program.


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.

The following functions take a process status code as returned by :func:`system`, :func:`wait`, or :func:`waitpid` as a parameter. They may be used to determine the disposition of a process.

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.

This class represents tunable scheduling parameters used in :func:`sched_setparam`, :func:`sched_setscheduler`, and :func:`sched_getparam`. It is immutable.

At the moment, there is only one possible parameter:

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 :mod:`os.path` module.

Miscellaneous Functions