os --- 各種作業系統介面

原始碼：Lib/os.py

該模組提供了一種便利的方式來操作與作業系統相關的功能。如果你想讀取或寫入檔案，請參閱 open() ，如果你想操作檔案路徑，請參閱 os.path 模組，如果你想透過命令列查看所有檔案中的所有內容，請查看 fileinput 模組。要建立臨時檔案和目錄，請參閱 tempfile 模組，要操作高級檔案和目錄，請參閱 shutil 模組。

關於這些功能的可用性說明：

  • Python 所有內建作業系統相關的模組設計是這樣：只要有相同的函式可使用，就會使用相同的介面 （interface）。舉例來說，os.stat(path) 函式會以相同格式回傳關於 path 的統計資訊（這剛好來自於 POSIX 的介面。）。

  • 對於特定的作業系統獨有的擴充功能也可以透過 os 取得，但使用它們的時候對於可移植性無疑會是個問題。

  • 所有接受檔案路徑和檔案名稱的函式皆接受位元組 (bytes) 和字串物件 (string objects)，且如果回傳檔案路徑或檔案名稱，則會產出相同型別的物件。

  • 在 VxWorks, 不支援 os.popen、os.fork、os.execv 和 os.spawn*p*。

  • 在 WebAssembly 平台和 Android 與 iOS 上，大部分 os 模組無法使用或行為不同。與行程 (process)（例如 fork()、execve()）與資源（例如 nice()）相關的 API 不可使用。其他諸如 getuid() 和 getpid() 的相關 API 是 emulated 或 stubs。WebAssembly 平台也缺少訊號相關支援（例如 kill()、wait()）。

備註

在檔案名稱和路徑找不到或無效的時候，或引數型別正確但作業系統不接受的時候，在此模組中的所有的函式都會引發 OSError（或其子類別）。

exception os.error

內建例外 OSError 的別名。

os.name

The name of the operating system dependent module imported. The following names have currently been registered: 'posix', 'nt', 'java'.

也參考

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 filesystem encoding and error handler to perform this conversion (see sys.getfilesystemencoding()).

The filesystem encoding and error handler are configured at Python startup by the PyConfig_Read() function: see filesystem_encoding and filesystem_errors members of PyConfig.

在 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 can raise UnicodeError.

另請參閱 locale encoding。

Python UTF-8 模式

在 3.7 版被加入: 更多資訊請見 PEP 540。

Python 在 UTF-8 模式下會忽略 locale encoding 並且強制使用 UTF-8 去編碼：

請注意，在 UTF-8 模式中，標準的串流設定會被 PYTHONIOENCODING 覆蓋（如同在預設在地化覺察 模式一樣）。

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

  • 命令列引數、環境變數及檔案名稱會以 UTF-8 編碼形式來被解碼成文字。

  • os.fsdecode() 和 os.fsencode() 使用 UTF-8 編碼。

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

The Python UTF-8 Mode is enabled if the LC_CTYPE locale is C or POSIX at Python startup (see the PyConfig_Read() function).

It can be enabled or disabled using the -X utf8 command line option and the PYTHONUTF8 environment variable.

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

The Python UTF-8 Mode can only be enabled at the Python startup. Its value can be read from sys.flags.utf8_mode.

See also the UTF-8 mode on Windows and the filesystem encoding and error handler.

也參考

PEP 686

Python 3.15 預設使用 Python UTF-8 模式

行程參數

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

os.ctermid()

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

可用性: Unix, not WASI.

os.environ

A mapping object where keys and values are strings that represent the process 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.

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

備註

呼叫 putenv() 並不會改變 os.environ，所以建議直接修改 os.environ。

備註

On some platforms, including FreeBSD and macOS, setting environ may cause memory leaks. Refer to the system documentation for putenv().

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.

也參考

os.reload_environ() 函式。

在 3.9 版的變更: Updated to support PEP 584's merge (|) and update (|=) operators.

os.environb

Bytes version of environ: a mapping object where both keys and values are bytes objects representing the process environment. environ and environb are synchronized (modifying environb updates environ, and vice versa).

environb is only available if supports_bytes_environ is True.

在 3.2 版被加入.

在 3.9 版的變更: Updated to support PEP 584's merge (|) and update (|=) operators.

os.reload_environ()

The os.environ and os.environb mappings are a cache of environment variables at the time that Python started. As such, changes to the current process environment are not reflected if made outside Python, or by os.putenv() or os.unsetenv(). Use os.reload_environ() to update os.environ and os.environb with any such changes to the current process environment.

警告

This function is not thread-safe. Calling it while the environment is being modified in another thread is an undefined behavior. Reading from os.environ or os.environb, or calling os.getenv() while reloading, may return an empty result.

在 3.14 版被加入.

os.chdir(path)
os.fchdir(fd)
os.getcwd()

These functions are described in Files and Directories.

os.fsencode(filename)

Encode path-like filename to the filesystem encoding and error handler; return bytes unchanged.

fsdecode() 是反函式。

在 3.2 版被加入.

在 3.6 版的變更: Support added to accept objects implementing the os.PathLike interface.

os.fsdecode(filename)

Decode the path-like filename from the filesystem encoding and error handler; return str unchanged.

fsencode() 是反函式。

在 3.2 版被加入.

在 3.6 版的變更: Support added to accept objects implementing the os.PathLike interface.

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.

在 3.6 版被加入.

class os.PathLike

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

在 3.6 版被加入.

abstractmethod __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)

Return the value of the environment variable key as a string if it exists, or default if it doesn't. key is a string. Note that since getenv() uses os.environ, the mapping of getenv() is similarly also captured on import, and the function may not reflect future environment changes.

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.

可用性: Unix, Windows.

os.getenvb(key, default=None)

Return the value of the environment variable key as bytes if it exists, or default if it doesn't. key must be bytes. Note that since getenvb() uses os.environb, the mapping of getenvb() is similarly also captured on import, and the function may not reflect future environment changes.

getenvb() is only available if supports_bytes_environ is True.

可用性: Unix.

在 3.2 版被加入.

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.

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

可用性: Unix, not WASI.

os.geteuid()

Return the current process's effective user id.

可用性: Unix, not WASI.

os.getgid()

Return the real group id of the current process.

可用性: Unix.

The function is a stub on WASI, see WebAssembly 平台 for more information.

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, because that group ID will otherwise be potentially omitted.

可用性: Unix, not WASI.

在 3.3 版被加入.

os.getgroups()

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

可用性: Unix, not WASI.

備註

On macOS, getgroups() behavior differs somewhat from other Unix platforms. If the Python interpreter was built with a deployment target of 10.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 to setgroups() if suitably privileged. If built with a deployment target greater than 10.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 to setgroups(), and its length is not limited to 16. The deployment target value, MACOSX_DEPLOYMENT_TARGET, can be obtained with sysconfig.get_config_var().

os.getlogin()

Return the name of the user logged in on the controlling terminal of the process. For most purposes, it is more useful to use getpass.getuser() since the latter checks the environment variables LOGNAME or USERNAME to find out who the user is, and falls back to pwd.getpwuid(os.getuid())[0] to get the login name of the current real user id.

可用性: Unix, Windows, not WASI.

os.getpgid(pid)

Return the process group id of the process with process id pid. If pid is 0, the process group id of the current process is returned.

可用性: Unix, not WASI.

os.getpgrp()

Return the id of the current process group.

可用性: Unix, not WASI.

os.getpid()

Return the current process id.

The function is a stub on WASI, see WebAssembly 平台 for more information.

os.getppid()

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

可用性: Unix, Windows, not WASI.

在 3.2 版的變更: 新增對 Windows 的支援。

os.getpriority(which, who)

Get program scheduling priority. The value which is one of PRIO_PROCESS, PRIO_PGRP, or PRIO_USER, and who is interpreted relative to which (a process identifier for PRIO_PROCESS, process group identifier for PRIO_PGRP, and a user ID for PRIO_USER). A zero value for who denotes (respectively) the calling process, the process group of the calling process, or the real user ID of the calling process.

可用性: Unix, not WASI.

在 3.3 版被加入.

os.PRIO_PROCESS
os.PRIO_PGRP
os.PRIO_USER

Parameters for the getpriority() and setpriority() functions.

可用性: Unix, not WASI.

在 3.3 版被加入.

os.PRIO_DARWIN_THREAD
os.PRIO_DARWIN_PROCESS
os.PRIO_DARWIN_BG
os.PRIO_DARWIN_NONUI

Parameters for the getpriority() and setpriority() functions.

可用性: macOS

在 3.12 版被加入.

os.getresuid()

Return a tuple (ruid, euid, suid) denoting the current process's real, effective, and saved user ids.

可用性: Unix, not WASI.

在 3.2 版被加入.

os.getresgid()

Return a tuple (rgid, egid, sgid) denoting the current process's real, effective, and saved group ids.

可用性: Unix, not WASI.

在 3.2 版被加入.

os.getuid()

Return the current process's real user id.

可用性: Unix.

The function is a stub on WASI, see WebAssembly 平台 for more information.

os.initgroups(username, gid, /)

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

可用性: Unix, not WASI, not Android.

在 3.2 版被加入.

os.putenv(key, value, /)

Set the environment variable named key to the string value. Such changes to the environment affect subprocesses started with os.system(), popen() or fork() and execv().

Assignments to items in os.environ are automatically translated into corresponding calls to putenv(); however, calls to putenv() don't update os.environ, so it is actually preferable to assign to items of os.environ. This also applies to getenv() and getenvb(), which respectively use os.environ and os.environb in their implementations.

也請見 os.reload_environ() 函式。

備註

On some platforms, including FreeBSD and macOS, setting environ may cause memory leaks. Refer to the system documentation for putenv().

引發一個附帶引數 key、value 的稽核事件 os.putenv。

在 3.9 版的變更: 此函式現在都會是可用的。

os.setegid(egid, /)

Set the current process's effective group id.

可用性: Unix, not WASI, not Android.

os.seteuid(euid, /)

Set the current process's effective user id.

可用性: Unix, not WASI, not Android.

os.setgid(gid, /)

Set the current process' group id.

可用性: Unix, not WASI, not Android.

os.setgroups(groups, /)

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

可用性: Unix, not WASI.

備註

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

os.setns(fd, nstype=0)

Reassociate the current thread with a Linux namespace. See the setns(2) and namespaces(7) man pages for more details.

If fd refers to a /proc/pid/ns/ link, setns() reassociates the calling thread with the namespace associated with that link, and nstype may be set to one of the CLONE_NEW* constants to impose constraints on the operation (0 means no constraints).

Since Linux 5.8, fd may refer to a PID file descriptor obtained from pidfd_open(). In this case, setns() reassociates the calling thread into one or more of the same namespaces as the thread referred to by fd. This is subject to any constraints imposed by nstype, which is a bit mask combining one or more of the CLONE_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 a fileno() method, or a raw file descriptor.

This example reassociates the thread with the init process's network namespace:

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

可用性: Linux >= 3.0 with glibc >= 2.14.

在 3.12 版被加入.

也參考

unshare() 函式。

os.setpgrp()

Call the system call setpgrp() or setpgrp(0, 0) depending on which version is implemented (if any). See the Unix manual for the semantics.

可用性: Unix, not WASI.

os.setpgid(pid, pgrp, /)

Call the system call setpgid() to set the process group id of the process with id pid to the process group with id pgrp. See the Unix manual for the semantics.

可用性: Unix, not WASI.

os.setpriority(which, who, priority)

Set program scheduling priority. The value which is one of PRIO_PROCESS, PRIO_PGRP, or PRIO_USER, and who is interpreted relative to which (a process identifier for PRIO_PROCESS, process group identifier for PRIO_PGRP, and a user ID for PRIO_USER). A zero value for who 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.

可用性: Unix, not WASI.

在 3.3 版被加入.

os.setregid(rgid,