os
— Miscellaneous operating system interfaces
Source code: Lib/os.py
This module provides a portable way of using operating system dependent functionality. If you just 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.
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.
-
On VxWorks, os.fork, os.execv and os.spawn*p* are not supported.
{note}All functions in this module raise
OSError
(or subclasses thereof) 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.
exception os.
error
os.
error
An alias for the built-in OSError
exception.
os.
name
os.
name
The name of the operating system dependent module imported. The following names have currently been registered: 'posix'
, 'nt'
, 'java'
.
{tip}
sys.platform
has a finer granularity.os.uname()
gives system-dependent version information.The
platform
module provides detailed checks for the system’s identity.
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()
).
Changed in version 3.1: 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 UnicodeErrors.
Process Parameters
These functions and data items provide information and operate on the current process and user.
os.
ctermid
()
os.
ctermid
()Return the filename corresponding to the controlling terminal of the process.
Availability: Unix.
os.
environ
os.
environ
A mapping object representing the string environment. For example, environ['HOME']
is the pathname of your home directory (on some platforms), and is equivalent to getenv("HOME")
in C.
This mapping is captured the first time the os
module is imported, typically during Python startup as part of processing site.py
. Changes to the environment made after this time are not reflected in os.environ
, except for changes made by modifying os.environ
directly.
This mapping may be used to modify the environment as well as query the environment. putenv()
will be called automatically when the mapping is modified.
On Unix, keys and values use sys.getfilesystemencoding()
and 'surrogateescape'
error handler. Use environb
if you would like to use a different encoding.
{note}Calling
putenv()
directly does not changeos.environ
, so it’s better to modifyos.environ
.
{note}On some platforms, including FreeBSD and Mac OS X, setting
environ
may cause 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 from os.environ
, and when one of the pop()
or clear()
methods is called.
Changed in version 3.9: Updated to support PEP 584’s merge (|
) and update (|=
) operators.
os.
environb
os.
environb
Bytes version of environ
: a mapping object representing the environment as byte strings. environ
and environb
are synchronized (modify environb
updates environ
, and vice versa).
environb
is only available if supports_bytes_environ
is True
.
New in version 3.2.
Changed in version 3.9: Updated to support PEP 584’s merge (|
) and update (|=
) operators.
os.
chdir
(path)os.
fchdir
(fd)os.
getcwd
()These functions are described in Files and Directories.
os.
fsencode
(filename)
os.
fsencode
(filename)Encode path-like filename to the filesystem encoding with 'surrogateescape'
error handler, or 'strict'
on Windows; return bytes
unchanged.
fsdecode()
is the reverse function.
New in version 3.2.
Changed in version 3.6: Support added to accept objects implementing the os.PathLike
interface.
os.
fsdecode
(filename)
os.
fsdecode
(filename)Decode the path-like filename from the filesystem encoding with 'surrogateescape'
error handler, or 'strict'
on Windows; return str
unchanged.
fsencode()
is the reverse function.
New in version 3.2.
Changed in version 3.6: Support added to accept objects implementing the os.PathLike
interface.
os.
fspath
(path)
os.
fspath
(path)Return the file system representation of the path.
If str
or bytes
is passed in, it is returned unchanged. Otherwise __fspath__()
is called and its value is returned as long as it is a str
or bytes
object. In all other cases, TypeError
is raised.
New in version 3.6.
class os.
PathLike
os.
PathLike
An abstract base class for objects representing a file system path, e.g. pathlib.PurePath
.
New in version 3.6.
abstractmethod __fspath__
()
__fspath__
()Return the file system path representation of the object.
The method should only return a str
or bytes
object, with the preference being for str
.
os.
getenv
(key, default=None)
os.
getenv
(key, default=None)Return the value of the environment variable key if it exists, or default if it doesn’t. key, default and the result are str.
On Unix, keys and values are decoded with sys.getfilesystemencoding()
and 'surrogateescape'
error handler. Use os.getenvb()
if you would like to use a different encoding.
Availability: most flavors of Unix, Windows.
os.
getenvb
(key, default=None)
os.
getenvb
(key, default=None)Return the value of the environment variable key if it exists, or default if it doesn’t. key, default and the result are bytes.
getenvb()
is only available if supports_bytes_environ
is True
.
Availability: most flavors of Unix.
New in version 3.2.
os.
get_exec_path
(env=None)
os.
get_exec_path
(env=None)Returns the list of directories that will be searched for a named executable, similar to a shell, when launching a process. env, when specified, should be an environment variable dictionary to lookup the PATH in. By default, when env is None
, environ
is used.
New in version 3.2.
os.
getegid
()
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.
os.
geteuid
()
os.
geteuid
()Return the current process’s effective user id.
Availability: Unix.
os.
getgid
()
os.
getgid
()Return the real group id of the current process.
Availability: Unix.
os.
getgrouplist
(user, group)
os.
getgrouplist
(user, group)Return list of group ids that user belongs to. If group is not in the list, it is included; typically, group is specified as the group ID field from the password record for user.
Availability: Unix.
New in version 3.3.
os.
getgroups
()
os.
getgroups
()Return list of supplemental group ids associated with the current process.
Availability: Unix.
{note}On Mac OS X,
getgroups()
behavior differs somewhat from other Unix platforms. If the Python interpreter was built with a deployment target of10.5
or earlier,getgroups()
returns the 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 user associated with the effective user id of the process; the group access list may change over the lifetime of the process, it is not affected by calls tosetgroups()
, and its length is not limited to 16. The deployment target value,MACOSX_DEPLOYMENT_TARGET
, can be obtained withsysconfig.get_config_var()
.
exception os.errorAn alias for the built-in OSError exception.
1326 0 1 years ago
os.nameThe name of the operating system dependent module imported. The following names h...
1470 0 1 years ago
File Names, Command Line Arguments, and Environment VariablesIn Python, file names, comman...
1746 0 1 years ago
Process ParametersThese functions and data items provide information and operate on the cu...
1813 0 1 years ago
os.ctermid()Return the filename corresponding to the controlling terminal of the process....
1399 0 1 years ago
os.environA mapping object representing the string environment. For example, environ['HOM...
1760 0 1 years ago
os.environbBytes version of environ: a mapping object representing the environment as byt...
1517 0 1 years ago
os.fsencode(filename)Encode path-like filename to the filesystem encoding with 'surrogate...
1738 0 1 years ago
os.fsdecode(filename)Decode the path-like filename from the filesystem encoding with 'sur...
1426 0 1 years ago
os.fspath(path)Return the file system representation of the path.If str or bytes is passe...
1497 0 1 years ago
class os.PathLikeAn abstract base class for objects representing a file system path, e.g....
1734 0 1 years ago
abstractmethod __fspath__()Return the file system path representation of the object.The m...
1192 0 1 years ago
os.getenv(key, default=None)Return the value of the environment variable key if it exists...
1435 0 1 years ago
os.getenvb(key, default=None)Return the value of the environment variable key if it exist...
1827 0 1 years ago
os.get_exec_path(env=None)Returns the list of directories that will be searched for a nam...
1110 0 1 years ago
os.getegid()Return the effective group id of the current process. This corresponds to th...
871 0 1 years ago
os.geteuid()Return the current process’s effective user id.Availability: Unix.
964 0 1 years ago
os.getgid()Return the real group id of the current process.Availability: Unix.
1274 0 1 years ago
os.getgrouplist(user, group)Return list of group ids that user belongs to. If group is no...
940 0 1 years ago
os.getgroups()Return list of supplemental group ids associated with the current process.A...
886 0 1 years ago