os.path --- 一般的なパス名操作

ソースコード: Lib/genericpath.py, Lib/posixpath.py (POSIX) 、 Lib/ntpath.py (Windows) 。

このモジュールはパス名を扱う際に便利な関数を実装しています。ファイルの読み書きをする際は open() を、ファイルシステムにアクセスするには os モジュールをご参照ください。パスの引数は文字列、バイト列、あるいは os.PathLike プロトコルを実装するあらゆるオブジェクトとして渡すことができます。

Unix シェルとは異なり、Python はあらゆるパス展開を 自動的には 行いません。アプリケーションがシェルのようなパス展開を必要とした場合は、 expanduser() や expandvars() といった関数を明示的に呼び出すことで行えます。(glob モジュールも参照してください)

参考

pathlib モジュールは高水準のパスオブジェクトを提供します。

注釈

以下のすべての関数は、そのパラメータにバイト列のみ、あるいは文字列のみ受け付けます。パスまたはファイル名を返す場合、返り値は同じ型のオブジェクトになります。

注釈

OS によって異なるパス名の決まりがあるため、標準ライブラリにはこのモジュールのいくつかのバージョンが含まれています。 os.path モジュールは常に現在 Python が動作している OS に適したパスモジュールであるため、ローカルのパスを扱うのに適しています。各々のモジュールをインポートして 常に 一つのフォーマットを利用することも可能です。これらはすべて同じインターフェースを持っています:

  • posixpath for UNIX-style paths

  • ntpath for Windows paths

バージョン 3.8 で変更: exists()、lexists()、isdir()、isfile()、islink()、ismount() は、OS レベルで表現できない文字やバイトを含むパスに対して、例外を送出する代わりに False を返すようになりました。

os.path.abspath(path)

Return a normalized absolutized version of the pathname path. On most platforms, this is equivalent to calling normpath(join(os.getcwd(), path)).

On Windows the path is normalized by the operating system, therefore the result can differ from normpath(join(os.getcwd(), path)). A drive-relative path is resolved against the current directory of the specified drive, and the drive letter is capitalized. Trailing dots and spaces are stripped. For example:

>>> os.path.abspath('c:spam')
'C:\\Temp\\spam'
>>> os.path.abspath('c:/temp/spam. . .')
'c:\\temp\\spam'

参考

os.path.join() and os.path.normpath().

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.path.basename(path, /)

パス名 path の末尾のファイル名部分を返します。これは関数 split() に path を渡した時に返されるペアの 2 番めの要素です。この関数が返すのは Unix の basename とは異なります; Unix の basename は '/foo/bar/' に対して 'bar' を返しますが、関数 basename() は空文字列 ('') を返します。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.path.commonpath(paths)

イテラブル paths に含まれる各パス名に共通する、最長のサブパスを返します。 paths に絶対パスと相対パスの両方が含まれる場合、異なるドライブのパスが含まれる場合、または paths が空の場合は ValueError を送出します。 commonprefix() と異なり、有効なパスを返します。

Added in version 3.5.

バージョン 3.6 で変更: path-like objects のシーケンスを受け入れるようになりました。

バージョン 3.13 で変更: シーケンスだけでなく、任意のイテラブルを渡せるようになりました。

os.path.commonprefix(list, /)

Return the longest string prefix (taken character-by-character) that is a prefix of all strings in list. If list is empty, return the empty string ('').

警告

This function may return invalid paths because it works a character at a time. If you need a common path prefix, then the algorithm implemented in this function is not secure. Use commonpath() for finding a common path prefix.

>>> 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 のディレクトリ名を返します。これは関数 split() に path を渡した時に返されるペアの 1 番めの要素です。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.path.exists(path)

path が実在するパスかオープンしているファイル記述子を参照している場合 True を返します。壊れたシンボリックリンクについては False を返します。一部のプラットフォームでは、たとえ path が物理的に存在していたとしても、要求されたファイルに対する os.stat() の実行権がなければこの関数が 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 では 2 つのスラッシュまたはバックスラッシュで始まるパスか、ドライブレター、コロン、スラッシュまたはバックスラッシュの並びで始まるパスを指します。

参考

abspath()

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

バージョン 3.13 で変更: Windows では、指定されたパスがちょうど 1 つのスラッシュまたはバックスラッシュで始まる場合に False を返すようになりました。

os.path.isfile(path)

path が 存在する 一般ファイルなら True を返します。 この関数はシンボリックリンクの先を辿るので、同じパスに対して islink() と isfile() の両方が真を返すことがあります。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.path.isdir(path, /)

path が 存在する ディレクトリなら True を返します。 この関数はシンボリックリンクの先を辿るので、同じパスに対して islink() と isdir() の両方が真を返すことがあります。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.path.isjunction(path)

path がジャンクションである 既存の ディレクトリエントリを指している場合は True を返します。 現在のプラットフォームがジャンクションをサポートしていない場合は、常に False を返します。

Added in version 3.12.

path が、シンボリックリンクである 既存の ディレクトリエントリを指している場合に True を返します。 Python ランタイムがシンボリックリンクをサポートしていないプラットフォームでは、常に False を返します。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.path.ismount(path)

Return True if pathname path is a mount point: a point in a file system where a different file system has been mounted. On POSIX, the function checks whether path's parent, path/.., is on a different device than path, or whether path/.. and path point to the same i-node on the same device --- this should detect mount points for all Unix and POSIX variants. It is not able to reliably detect bind mounts on the same filesystem. On Linux systems, it will always return True for btrfs subvolumes, even if they aren't mount points. On Windows, a drive letter root and a share UNC are always mount points, and for any other path GetVolumePathName is called to see if it is different from the input path.

バージョン 3.4 で変更: Windows でルート以外のマウントポイントの検出をサポートしました。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.path.isdevdrive(path)

パス名 path が Windows の Dev Drive 上にある場合は True を返します。 Dev Drive は開発者向けの用途に最適化されており、ファイルの読み書きを高速に行えます。 ソースコード、ビルド用の一時ディレクトリ、パッケージのキャッシュ、その他の入出力が多い操作に使うことが推奨されます。

認識可能なドライブを含まないパスなど、不正なパスに対してはエラーを送出する場合がありますが、Dev Drive をサポートしないプラットフォームでは False を返します。 Dev Drive を有効にする方法や作成する方法については、Windows のドキュメント を参照してください。

Added in version 3.12.

バージョン 3.13 で変更: すべてのプラットフォームで利用できるようになりました。 Dev Drive をサポートしないプラットフォームでは常に False を返します。

os.path.isreserved(path)

path が現在のシステムで予約済みのパス名である場合は True を返します。

Windows では、末尾が空白またはドットのファイル名、コロン ("name:stream" のようなファイルストリーム)、ワイルドカード文字 ('*?"<>')、パイプ文字、ASCII 制御文字を含むファイル名、および "NUL"、"CON"、"CONIN$"、"CONOUT$"、"AUX"、"PRN"、"COM1"、"LPT1" などの DOS デバイス名が予約されています。

注釈

この関数は、ほとんどの Windows システムで使われる予約済みパスの規則を近似します。 これらの規則は Windows のリリースとともに変化します。 規則の変更が広く利用されるようになった場合、将来の Python リリースでこの関数が更新される可能性があります。

利用可能な環境: Windows.

Added in version 3.13.

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

Join one or more path segments intelligently. The return value is the concatenation of path and all members of *paths, with exactly one directory separator following each non-empty part, except the last. That is, the result will only end in a separator if the last part is either empty or ends in a separator.

If a segment is an absolute path (which on Windows requires both a drive and a root), then all previous segments are ignored and joining continues from the absolute path segment. On Linux, for example:

>>> os.path.join('/home/foo', 'bar')
'/home/foo/bar'
>>> os.path.join('/home/foo', '/home/bar')
'/home/bar'

On Windows, the drive is not reset when a rooted path segment (e.g., r'\foo') is encountered. If a segment is on a different drive or is an absolute path, all previous segments are ignored and the drive is reset. For example:

>>> os.path.join('c:\\', 'foo')
'c:\\foo'
>>> os.path.join('c:\\foo', 'd:\\bar')
'd:\\bar'

Note that since there is a current directory for each drive, os.path.join("c:", "foo") represents a path relative to the current directory on drive C: (c:foo), not c:\foo.

バージョン 3.6 で変更: path と paths が path-like object を受け付けるようになりました。

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 に従い、パス名がちょうど 2 つのスラッシュで始まる場合、その後の最初の要素を実装で定義した方法で解釈することがあります。 ただし、先頭のスラッシュが 3 つ以上の場合は 1 つとして扱います。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

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

Return the canonical path of the specified filename, eliminating any symbolic links encountered in the path (if they are supported by the operating system). On Windows, this function will also resolve MS-DOS (also called 8.3) style names such as C:\\PROGRA~1 to C:\\Program Files. The returned path uses the case reported by the operating system, which can differ from the case of path, in particular the drive letter is capitalized.

By default, the path is evaluated up to the first component that does not exist, is a symlink loop, or whose evaluation raises OSError. All such components are appended unchanged to the existing part of the path.

Some errors that are handled this way include "access denied", "not a directory", or "bad argument to internal function". Thus, the resulting path may be missing or inaccessible, may still contain links or loops, and may traverse non-directories.

This behavior can be modified by keyword arguments:

If strict is True, the first error encountered when evaluating the path is re-raised. In particular, FileNotFoundError is raised if path does not exist, or another OSError if it is otherwise inaccessible.

If strict is os.path.ALLOW_MISSING, errors other than FileNotFoundError are re-raised (as with strict=True). Thus, the returned path will not contain any symbolic links, but the named file and some of its parent directories may be missing.

注釈

この関数は、パスを正規の形にするオペレーティングシステムの処理を模倣します。 リンクとそれに続くパス要素との関係について、この処理は Windows と UNIX で少し異なります。

オペレーティングシステムの API は必要に応じてパスを正規の形にするため、通常はこの関数を呼び出す必要はありません。

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

バージョン 3.8 で変更: Windows においてシンボリックリンクとジャンクションが解決されるようになりました。

バージョン 3.10 で変更: strict 引数が追加されました。

バージョン 3.13.4 で変更: The ALLOW_MISSING value for the strict parameter was added.

os.path.ALLOW_MISSING

Special value used for the strict argument in realpath().

Added in version 3.13.4.

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

カレントディレクトリあるいはオプションの start ディレクトリからの path への相対パスを返します。これはパス計算で行っており、ファイルシステムにアクセスして 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, /)

Split the pathname path into a pair, (head, tail) where tail is the last pathname component and head is everything leading up to that. The tail part will never contain a slash; if path ends in a slash, tail will be empty. If there is no slash in path, head will be empty. If path is empty, both head and tail are empty. Trailing slashes are stripped from head unless it is the root (one or more slashes only). In all cases, join(head, tail) returns a path to the same location as path (but the strings may differ). Also see the functions join(), dirname() and 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 が相対パスの場合)、1 つのスラッシュ (path が絶対パスの場合)、または 2 つのスラッシュ (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')

Added in version 3.12.

os.path.splitext(path, /)

パス名 path を root + ext == path となるペア (root, ext) に分割します。 拡張子 ext は空か、ピリオドで始まり、ピリオドを高々 1 つ含む文字列です。

パスに拡張子がない場合、ext は '' になります。

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

パスに拡張子がある場合、ext には先頭のピリオドを含めた拡張子が設定されます。 それより前のピリオドは無視されることに注意してください。

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

パスの最後の要素の先頭にあるピリオドは、root の一部とみなします。

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

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

os.path.supports_unicode_filenames

ファイル名に任意の Unicode 文字列を (システムの制限内で) 使用できる場合は True になります。