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。