os.path — 常见的路径名操作

源代码: Lib/genericpath.py, Lib/posixpath.py (适用于 POSIX) 和 Lib/ntpath.py (适用于 Windows)。

此模块实现了路径名的一些有用函数。要读取或写入文件，请参阅 open()；要访问文件系统，请参阅 os 模块。路径参数可以作为字符串、字节串或实现 os.PathLike 协议的任何对象传递。

与 Unix shell 不同，Python 不执行任何 自动 路径扩展。当应用程序需要类似 shell 的路径扩展时，可以显式调用 expanduser() 和 expandvars() 等函数。（另请参阅 glob 模块。）

参见

pathlib 模块提供高级路径对象。

备注

所有这些函数都只接受字节或字符串对象作为其参数。如果返回路径或文件名，结果将是相同类型的对象。

备注

由于不同的操作系统有不同的路径名约定，标准库中有几个版本的此模块。os.path 模块始终是适用于 Python 运行的操作系统的路径模块，因此可用于本地路径。但是，如果您想要操作 始终 采用不同格式之一的路径，您也可以导入和使用各个模块。它们都具有相同的接口。

  • posixpath 适用于 UNIX 风格的路径

  • ntpath 适用于 Windows 路径

版本 3.8 中的变更: exists(), lexists(), isdir(), isfile(), islink() 和 ismount() 现在对于包含操作系统级别无法表示的字符或字节的路径返回 False 而不是引发异常。

os.path.abspath(path)

返回路径名 path 的规范化绝对版本。在大多数平台上，这相当于以下调用函数 normpath(): normpath(join(os.getcwd(), path))。

在 3.6 版本发生变更: 接受 path-like object。

os.path.basename(path, /)

返回路径名 path 的基本名称。这是将 path 传递给函数 split() 返回的对的第二个元素。请注意，此函数的结果与 Unix basename 程序不同；basename 对于 '/foo/bar/' 返回 'bar'，而 basename() 函数返回空字符串 ('')。

在 3.6 版本发生变更: 接受 path-like object。

os.path.commonpath(paths)

返回可迭代对象 paths 中每个路径名的最长公共子路径。如果 paths 包含绝对路径和相对路径，或者 paths 位于不同的驱动器上，或者 paths 为空，则引发 ValueError。与 commonprefix() 不同，此函数返回一个有效路径。

在 3.5 版本加入。

版本 3.6 中的变更: 接受 路径类对象 序列。

版本 3.13 中的变更: 现在可以传递任何可迭代对象，而不仅仅是序列。

os.path.commonprefix(list, /)

返回作为 list 中所有路径前缀的最长路径前缀（逐字符）。如果 list 为空，则返回空字符串 ('')。

备注

此函数可能会返回无效路径，因为它逐字符工作。要获取有效路径，请参阅 commonpath()。

>>> os.path.commonprefix(['/usr/lib', '/usr/local/lib'])
'/usr/l'

>>> os.path.commonpath(['/usr/lib', '/usr/local/lib'])
'/usr'

在 3.6 版本发生变更: 接受 path-like object。

os.path.dirname(path, /)

返回路径名 path 的目录名。这是将 path 传递给函数 split() 返回的对的第一个元素。

在 3.6 版本发生变更: 接受 path-like object。

os.path.exists(path)

如果 path 指的是一个现有路径或一个打开的文件描述符，则返回 True。对于损坏的符号链接返回 False。在某些平台上，如果未授予执行请求文件的 os.stat() 的权限，即使 path 物理存在，此函数也可能返回 False。

版本 3.3 中的变更: path 现在可以是一个整数：如果它是一个打开的文件描述符，则返回 True，否则返回 False。

在 3.6 版本发生变更: 接受 path-like object。

os.path.lexists(path)

如果 path 指的是一个现有路径，包括损坏的符号链接，则返回 True。在缺少 os.lstat() 的平台上，等同于 exists()。

在 3.6 版本发生变更: 接受 path-like object。

os.path.expanduser(path)

在 Unix 和 Windows 上，返回参数，其中开头的 ~ 或 ~user 被替换为该 user 的主目录。

在 Unix 上，如果环境变量 HOME 已设置，则开头的 ~ 将被替换；否则通过内置模块 pwd 在密码目录中查找当前用户的主目录。开头的 ~user 直接在密码目录中查找。

在 Windows 上，如果设置了 USERPROFILE，则将使用它；否则将使用 HOMEPATH 和 HOMEDRIVE 的组合。开头的 ~user 通过检查当前用户主目录的最后一个目录组件是否与 USERNAME 匹配来处理，如果匹配则替换它。

如果扩展失败或路径不以波浪号开头，则路径保持不变返回。

在 3.6 版本发生变更: 接受 path-like object。

版本 3.8 中的变更: 在 Windows 上不再使用 HOME。

os.path.expandvars(path)

返回扩展了环境变量的参数。形式为 $name 或 ${name} 的子字符串将替换为环境变量 name 的值。格式错误的变量名和对不存在变量的引用保持不变。

在 Windows 上，除了 $name 和 ${name} 之外，还支持 %name% 扩展。

在 3.6 版本发生变更: 接受 path-like object。

os.path.getatime(path, /)

返回 path 的最后访问时间。返回值是一个浮点数，表示自纪元以来的秒数（参阅 time 模块）。如果文件不存在或无法访问，则引发 OSError。

os.path.getmtime(path, /)

返回 path 的最后修改时间。返回值是一个浮点数，表示自纪元以来的秒数（参阅 time 模块）。如果文件不存在或无法访问，则引发 OSError。

在 3.6 版本发生变更: 接受 path-like object。

os.path.getctime(path, /)

返回系统的 ctime，在某些系统（如 Unix）上是最后元数据更改时间，而在其他系统（如 Windows）上是 path 的创建时间。返回值是一个浮点数，表示自纪元以来的秒数（参阅 time 模块）。如果文件不存在或无法访问，则引发 OSError。

在 3.6 版本发生变更: 接受 path-like object。

os.path.getsize(path, /)

返回 path 的大小，以字节为单位。如果文件不存在或无法访问，则引发 OSError。

在 3.6 版本发生变更: 接受 path-like object。

os.path.isabs(path, /)

如果 path 是一个绝对路径名，则返回 True。在 Unix 上，这意味着它以斜杠开头；在 Windows 上，它以两个（反）斜杠开头，或以驱动器号、冒号和（反）斜杠组合开头。

在 3.6 版本发生变更: 接受 path-like object。

版本 3.13 中的变更: 在 Windows 上，如果给定路径恰好以一个（反）斜杠开头，则返回 False。

os.path.isfile(path)

如果 path 是一个 现有 的常规文件，则返回 True。这会跟随符号链接，因此对于同一个路径，islink() 和 isfile() 都可以为 true。

在 3.6 版本发生变更: 接受 path-like object。

os.path.isdir(path, /)

如果 path 是一个 现有 目录，则返回 True。这会跟随符号链接，因此对于同一个路径，islink() 和 isdir() 都可以为 true。

在 3.6 版本发生变更: 接受 path-like object。

os.path.isjunction(path)

如果 path 指的是一个 现有 的目录条目，并且该条目是一个连接点，则返回 True。如果当前平台不支持连接点，则始终返回 False。

3.12 新版功能.

如果 path 指的是一个 现有 的目录条目，并且该条目是一个符号链接，则返回 True。如果 Python 运行时不支持符号链接，则始终返回 False。

在 3.6 版本发生变更: 接受 path-like object。

os.path.ismount(path)

如果路径名 path 是一个 挂载点，即文件系统中挂载了不同文件系统的点，则返回 True。在 POSIX 上，此函数检查 path 的父目录 path/.. 是否与 path 位于不同的设备上，或者 path/.. 和 path 是否指向同一设备上的同一 i-node——这应该能检测所有 Unix 和 POSIX 变体中的挂载点。它无法可靠地检测同一文件系统上的绑定挂载。在 Linux 系统上，即使 btrfs 子卷不是挂载点，它也始终返回 True。在 Windows 上，驱动器盘符根目录和共享 UNC 始终是挂载点，对于任何其他路径，将调用 GetVolumePathName 以查看它是否与输入路径不同。

版本 3.4 中的变更: 增加了对 Windows 上非根挂载点检测的支持。

在 3.6 版本发生变更: 接受 path-like object。

os.path.isdevdrive(path)

如果路径名 path 位于 Windows 开发驱动器上，则返回 True。开发驱动器针对开发人员场景进行了优化，并为读写文件提供更快的性能。建议将其用于源代码、临时构建目录、包缓存和其他 IO 密集型操作。

对于无效路径（例如，没有可识别驱动器的路径）可能会引发错误，但在不支持开发驱动器的平台上返回 False。有关启用和创建开发驱动器的信息，请参阅 Windows 文档。

3.12 新版功能.

版本 3.13 中的变更: 此函数现在可在所有平台上使用，并且在不支持开发驱动器的平台上始终返回 False。

os.path.isreserved(path)

如果 path 是当前系统上的保留路径名，则返回 True。

在 Windows 上，保留文件名包括以空格或点结尾的文件名；包含冒号（即文件流，如“name:stream”）、通配符（即 '*?"<>'）、管道或 ASCII 控制字符的文件名；以及 DOS 设备名，如“NUL”、“CON”、“CONIN$”、“CONOUT$”、“AUX”、“PRN”、“COM1”和“LPT1”。

备注

此函数近似于大多数 Windows 系统上的保留路径规则。这些规则在不同的 Windows 版本中随时间变化。此函数可能会在未来的 Python 版本中更新，因为规则的更改变得广泛可用。

可用性: Windows。

在 3.13 版本加入。

os.path.join(path, /, *paths)

智能地连接一个或多个路径段。返回值是 path 和 *paths 所有成员的连接，每个非空部分之后恰好有一个目录分隔符，除了最后一个。也就是说，结果只有在最后一部分为空或以分隔符结尾时才以分隔符结尾。如果一个段是绝对路径（在 Windows 上需要驱动器和根），则所有先前的段都将被忽略，并从绝对路径段继续连接。

在 Windows 上，当遇到根路径段（例如，r'\foo'）时，驱动器不会重置。如果一个段在不同的驱动器上或是一个绝对路径，则所有先前的段都将被忽略，并且驱动器将被重置。请注意，由于每个驱动器都有一个当前目录，os.path.join("c:", "foo") 表示相对于驱动器 C: 上的当前目录的路径 (c:foo)，而不是 c:\foo。

版本 3.6 中的变更: 接受 path 和 paths 的 路径类对象。

os.path.normcase(path, /)

规范化路径名的大小写。在 Windows 上，将路径名中的所有字符转换为小写，并将正斜杠转换为反斜杠。在其他操作系统上，返回未更改的路径。

在 3.6 版本发生变更: 接受 path-like object。

os.path.normpath(path)

通过折叠冗余分隔符和上级引用来规范化路径名，以便 A//B、A/B/、A/./B 和 A/foo/../B 都变为 A/B。此字符串操作可能会更改包含符号链接的路径的含义。在 Windows 上，它将正斜杠转换为反斜杠。要规范化大小写，请使用 normcase()。

备注

在 POSIX 系统上，根据 IEEE Std 1003.1 2013 Edition; 4.13 Pathname Resolution，如果路径名以恰好两个斜杠开头，则紧跟在引导字符后面的第一个组件可以以实现定义的方式解释，尽管超过两个引导字符应被视为单个字符。

在 3.6 版本发生变更: 接受 path-like object。

os.path.realpath(path, /, *, strict=False)

返回指定文件名的规范路径，消除路径中遇到的任何符号链接（如果操作系统支持）。在 Windows 上，此函数还将解析 MS-DOS（也称为 8.3）风格的名称，例如 C:\\PROGRA~1 到 C:\\Program Files。

默认情况下，路径将被评估，直到遇到第一个不存在的组件、符号链接循环或其评估引发 OSError。所有此类组件都将不变地附加到路径的现有部分。

以这种方式处理的一些错误包括“访问被拒绝”、“不是目录”或“内部函数参数错误”。因此，生成的路径可能缺失或无法访问，可能仍然包含链接或循环，并且可能遍历非目录。

此行为可以通过关键字参数修改。

如果 strict 为 True，则在评估路径时遇到的第一个错误将被重新引发。特别是，如果 path 不存在，则引发 FileNotFoundError，如果它无法访问，则引发另一个 OSError。

如果 strict 为 os.path.ALLOW_MISSING，则除了 FileNotFoundError 之外的错误都会被重新引发（与 strict=True 相同）。因此，返回的路径将不包含任何符号链接，但指定的文件及其某些父目录可能缺失。

备注

此函数模拟操作系统使路径规范化的过程，该过程在 Windows 和 UNIX 之间在链接和后续路径组件如何交互方面略有不同。

操作系统 API 会根据需要使路径规范化，因此通常不需要调用此函数。

在 3.6 版本发生变更: 接受 path-like object。

版本 3.8 中的变更: 现在在 Windows 上解析符号链接和连接点。

版本 3.10 中的变更: 添加了 strict 参数。

版本 3.14 中的变更: 添加了 strict 参数的 ALLOW_MISSING 值。

os.path.ALLOW_MISSING

用于 realpath() 中 strict 参数的特殊值。

在 3.14 版本加入。

os.path.relpath(path, start=os.curdir)

返回到 path 的相对文件路径，可以从当前目录或可选的 start 目录。这是一个路径计算：不会访问文件系统来确认 path 或 start 的存在或性质。在 Windows 上，当 path 和 start 位于不同的驱动器时，会引发 ValueError。

start 默认为 os.curdir。

在 3.6 版本发生变更: 接受 path-like object。

os.path.samefile(path1, path2, /)

如果两个路径名参数指的是同一个文件或目录，则返回 True。这由设备号和 i-node 号确定，如果对任一路径名调用 os.stat() 失败，则引发异常。

版本 3.2 中的变更: 增加了 Windows 支持。

版本 3.4 中的变更: Windows 现在使用与其他所有平台相同的实现。

在 3.6 版本发生变更: 接受 path-like object。

os.path.sameopenfile(fp1, fp2)

如果文件描述符 fp1 和 fp2 指的是同一个文件，则返回 True。

版本 3.2 中的变更: 增加了 Windows 支持。

在 3.6 版本发生变更: 接受 path-like object。

os.path.samestat(stat1, stat2, /)

如果 stat 元组 stat1 和 stat2 指的是同一个文件，则返回 True。这些结构可能由 os.fstat()、os.lstat() 或 os.stat() 返回。此函数实现了 samefile() 和 sameopenfile() 使用的底层比较。

版本 3.4 中的变更: 增加了 Windows 支持。

os.path.split(path, /)

将路径名 path 分割成一对 (head, tail)，其中 tail 是最后一个路径名组件，head 是其之前的所有内容。tail 部分永远不会包含斜杠；如果 path 以斜杠结尾，则 tail 将为空。如果 path 中没有斜杠，则 head 将为空。如果 path 为空，则 head 和 tail 都为空。尾部斜杠将从 head 中剥离，除非它是根（仅包含一个或多个斜杠）。在所有情况下，join(head, tail) 返回与 path 相同位置的路径（但字符串可能不同）。另请参阅函数 dirname() 和 basename()。

在 3.6 版本发生变更: 接受 path-like object。

os.path.splitdrive(path, /)

将路径名 path 分割成一对 (drive, tail)，其中 drive 是一个挂载点或空字符串。在不使用驱动器规范的系统上，drive 将始终为空字符串。在所有情况下，drive + tail 将与 path 相同。

在 Windows 上，将路径名分割为驱动器/UNC 共享点和相对路径。

如果路径包含驱动器号，则 drive 将包含直到冒号（包括冒号）的所有内容。

>>> splitdrive("c:/dir")
("c:", "/dir")

如果路径包含 UNC 路径，则 drive 将包含主机名和共享。

>>> splitdrive("//host/computer/dir")
("//host/computer", "/dir")

在 3.6 版本发生变更: 接受 path-like object。

os.path.splitroot(path, /)

将路径名 path 分割成一个包含 3 个元素的元组 (drive, root, tail)，其中 drive 是设备名或挂载点，root 是驱动器后的分隔符字符串，tail 是根之后的所有内容。这些元素中的任何一个都可能是空字符串。在所有情况下，drive + root + tail 将与 path 相同。

在 POSIX 系统上，drive 始终为空。root 可能为空（如果 path 是相对路径），单个正斜杠（如果 path 是绝对路径），或两个正斜杠（根据 IEEE Std 1003.1-2017; 4.13 Pathname Resolution 实现定义）。例如：

>>> splitroot('/home/sam')
('', '/', 'home/sam')
>>> splitroot('//home/sam')
('', '//', 'home/sam')
>>> splitroot('///home/sam')
('', '/', '//home/sam')

在 Windows 上，drive 可能为空、驱动器盘符名称、UNC 共享或设备名称。root 可能为空、正斜杠或反斜杠。例如：

>>> splitroot('C:/Users/Sam')
('C:', '/', 'Users/Sam')
>>> splitroot('//Server/Share/Users/Sam')
('//Server/Share', '/', 'Users/Sam')

3.12 新版功能.

os.path.splitext(path, /)

将路径名 path 分割成一对 (root, ext)，使得 root + ext == path，并且扩展名 ext 为空或以句点开头且最多包含一个句点。

如果路径不包含扩展名，则 ext 将为 ''。

>>> splitext('bar')
('bar', '')

如果路径包含扩展名，则 ext 将设置为此扩展名，包括前导句点。请注意，之前的句点将被忽略。

>>> splitext('foo.bar.exe')
('foo.bar', '.exe')
>>> splitext('/foo/bar.exe')
('/foo/bar', '.exe')

路径的最后一个组件的前导句点被视为根的一部分。

>>> splitext('.cshrc')
('.cshrc', '')
>>> splitext('/foo/....jpg')
('/foo/....jpg', '')

在 3.6 版本发生变更: 接受 path-like object。

os.path.supports_unicode_filenames

如果任意 Unicode 字符串可以用作文件名（在文件系统施加的限制内），则为 True。