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

These functions create new :term:`file objects <file object>`. (See also :func:`open`.)

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.

open() flag constants

The following constants are options for the flags parameter to the :func:`` 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.

Files and Directories

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.

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