源代碼:?Lib/posixpath.py?(用于 POSIX) 和?Lib/ntpath.py?(用于 Windows)。

---

此模塊實現了一些有用的路徑名稱相關函數。 要讀取或寫入文件請參見?open()，對于訪問文件系統請參閱?os?模塊。 傳給 path 形參的可以是字符串、字節串或者任何實現了?os.PathLike?協議的對象。

與 Unix 不同，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(join(os.getcwd(),?path))?的方式調用?normpath()?函數。

在 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?在不同的驅動器上，或?paths?為空，則拋出?ValueError?異常。與?commonprefix()?不同，本方法返回有效路徑。

可用性: Unix, Windows。

3.5 新版功能.

在 3.6 版更改:?接受一個?類路徑對象?序列。

os.path.commonprefix(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。對于失效的符號鏈接，也返回?True。在缺失?os.lstat()?的平臺上等同于?exists()。

在 3.6 版更改:?接受一個?path-like object。

os.path.expanduser(path)

在 Unix 和 Windows 上，將參數中開頭部分的?~?或?~user?替換為當前?用戶?的家目錄并返回。

在 Unix 上，開頭的?~?會被環境變量?HOME?代替，如果變量未設置，則通過內置模塊?pwd?在 password 目錄中查找當前用戶的主目錄。以?~user?開頭則直接在 password 目錄中查找。

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

返回?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。

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)

Return?True?如果?path?指向的?現有?目錄條目是一個連接點。 則當連接點在當前平臺不受支持時將總是返回?False。

3.12 新版功能.

os.path.islink(path)

如果?path?指向的?現有?目錄條目是一個符號鏈接，則返回?True。如果 Python 運行時不支持符號鏈接，則總是返回?False。

在 3.6 版更改:?接受一個?path-like object。

os.path.ismount(path)

如果路徑?path?是?掛載點?（文件系統中掛載其他文件系統的點），則返回?True。在 POSIX 上，該函數檢查?path?的父目錄?path/..?是否在與?path?不同的設備上，或者?path/..?和?path?是否指向同一設備上的同一 inode（這一檢測掛載點的方法適用于所有 Unix 和 POSIX 變體）。本方法不能可靠地檢測同一文件系統上的綁定掛載 (bind mount)。在 Windows 上，盤符和共享 UNC 始終是掛載點，對于任何其他路徑，將調用?GetVolumePathName?來查看它是否與輸入的路徑不同。

3.4 新版功能:?支持在 Windows 上檢測非根掛載點。

在 3.6 版更改:?接受一個?path-like object。

os.path.isdevdrive(path)

如果路徑名?path?位于一個 Windows Dev 驅動器則返回?True。 Dev Drive 針對開發者場景進行了優化，并為讀寫文件提供更快的性能。 推薦用于源代碼、臨時構建目錄、包緩存以及其他的 IO 密集型操作。

對于無效的路徑可能引發錯誤，例如，沒有可識別的驅動器的路徑，但在不支持 Dev 驅動器的平臺上將返回?False。 請參閱?Windows 文檔?了解有關啟用并創建 Dev 驅動器的信息。

可用性: Windows。

3.12 新版功能.

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)

返回指定文件的規范路徑，消除路徑中存在的任何符號鏈接（如果操作系統支持）。

如果一個路徑不存在或是遇到了符號鏈接循環，并且?strict?為?True，則會引發?OSError。 如果?strict?為?False，則會盡可能地解析路徑并添加結果而不檢查路徑是否存在。

備注

這個函數會模擬操作系統生成規范路徑的過程，Windows 與 UNIX 的這個過程在處理鏈接和后續路徑組成部分的交互方式上有所差異。

操作系統 API 會根據需要來規范化路徑，因此通常不需要調用此函數。

在 3.6 版更改:?接受一個?path-like object。

在 3.8 版更改:?在 Windows 上現在可以正確解析符號鏈接和交接點 (junction point)。

在 3.10 版更改:?增加了?strict?形參。

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

返回從當前目錄或可選的?start?目錄至?path?的相對文件路徑。 這只是一個路徑計算：不會訪問文件系統來確認?path?或?start?是否存在或其性質。 在 Windows 上，當?path?和?start?位于不同驅動器時將引發?ValueError。

start?默認為?os.curdir。

可用性: Unix, Windows。

在 3.6 版更改:?接受一個?path-like object。

os.path.samefile(path1,?path2)

如果兩個路徑都指向相同的文件或目錄，則返回?True。這由設備號和 inode 號確定，在任一路徑上調用?os.stat()?失敗則拋出異常。

可用性: Unix, Windows。

在 3.2 版更改:?添加了對 Windows 的支持。

在 3.4 版更改:?Windows現在使用與其他所有平臺相同的實現。

在 3.6 版更改:?接受一個?path-like object。

os.path.sameopenfile(fp1,?fp2)

如果文件描述符?fp1?和?fp2?指向相同文件，則返回?True。

可用性: Unix, Windows。

在 3.2 版更改:?添加了對 Windows 的支持。

在 3.6 版更改:?接受一個?path-like object。

os.path.samestat(stat1,?stat2)

如果 stat 元組?stat1?和?stat2?指向相同文件，則返回?True。這些 stat 元組可能是由?os.fstat()、os.lstat()?或?os.stat()?返回的。本函數實現了?samefile()?和?sameopenfile()?底層所使用的比較過程。

可用性: Unix, Windows。

在 3.4 版更改:?添加了對 Windows 的支持。

在 3.6 版更改:?接受一個?path-like object。

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 根節點和相對路徑。

如果路徑 path 包含盤符，則 drive 將包含冒號之前的所有內容包括冒號本身:

>>>

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

如果路徑包含 UNC 路徑，則 drive 將包含主機名和 share:

>>>

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

在 3.6 版更改:?接受一個?path-like object。

os.path.splitroot(path)

將路徑名?path?拆分為一個 3 元組?(drive,?root,?tail)?其中?drive?是設置名或掛載點，root?是表示 drive 之后的分隔符的字符串，而?tail?則為 root 之后的所有內容。 這此條目均可以為空字符串。 在所有情況下，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 share 或是設備名稱。?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?為空或以句點打頭并最多只包含一個句點。

如果路徑 path 不包含擴展名，則?ext?將為?'':

>>>

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

如果路徑 path 包含擴展名，則?ext?將被設為該擴展名，包括打頭的句點。 請注意在其之前的句點將被忽略:

>>>

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

path 中最后一部分如果以點號開頭則會被視為 root 的一部分:

>>>

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

在 3.6 版更改:?接受一個?path-like object。

os.path.supports_unicode_filenames

如果（在文件系統限制下）允許將任意 Unicode 字符串用作文件名，則為?True。