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

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

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

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

参考

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

注釈

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

注釈

オペレーティングシステムによってパス名の規則が異なるため、標準ライブラリにはこのモジュールの複数の版があります。 os.path は常に Python が動作しているオペレーティングシステムに適したパスモジュールであり、ローカルのパスに使えます。一方、特定の形式のパスを常に扱いたい場合は、個々のモジュールをインポートして使うこともできます。いずれも同じインターフェースを持ちます:

UNIX 形式のパスを扱う posixpath
Windows のパスを扱う ntpath

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

os.path.abspath(path)¶

パス名 path を正規化された絶対パスにして返します。ほとんどのプラットフォームでは、normpath(join(os.getcwd(), path)) の呼び出しと同等です。

Windows ではオペレーティングシステムがパスを正規化するため、結果は normpath(join(os.getcwd(), path)) と異なる場合があります。ドライブ相対パスは、指定されたドライブのカレントディレクトリを基準に解決され、ドライブレターは大文字になります。末尾のドットと空白は取り除かれます。例えば、次のようになります。

>>> 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, /)¶

list 内のすべての文字列に共通する、最長の接頭辞を文字単位で求めて返します。 list が空の場合は空文字列 ('') を返します。

警告

この関数は 1 文字ずつ処理するため、無効なパスを返す場合があります。 パスの共通の接頭辞 が必要な場合、この関数が実装するアルゴリズムは安全ではありません。パスの共通の接頭辞を求めるには 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 を受け入れるようになりました。

バージョン 3.15 で非推奨: パスの接頭辞については os.path.commonpath() の使用を推奨し、この関数は非推奨になりました。 os.path.commonprefix() 関数が非推奨となるのは、その名前と所属するモジュールが誤解を招くためです。パス操作のモジュールに含まれているにもかかわらず、パスの接頭辞を扱う用途には安全ではなく、使うことで Python プログラムに誤ってパストラバーサルの脆弱性を持ち込みやすくなっています。

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.

os.path.islink(path)¶: 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)¶

1 つ以上のパス要素を適切に連結します。返り値は path と *paths のすべての要素を連結したもので、最後以外の空でない各要素の後には、ディレクトリ区切り文字がちょうど 1 つ入ります。つまり、結果が区切り文字で終わるのは、最後の要素が空か、区切り文字で終わっている場合だけです。

絶対パスの要素が現れると (Windows ではドライブとルートの両方が必要です)、それより前のすべての要素を無視し、その絶対パスから連結を続けます。例えば Linux では次のようになります。

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

Windows では、ルートから始まるパス要素 (例えば r'\foo') が現れても、ドライブは変更されません。異なるドライブ上の要素や絶対パスが現れた場合は、それより前のすべての要素を無視し、ドライブも設定し直します。例えば、次のようになります。

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

ドライブごとにカレントディレクトリがあるため、os.path.join("c:", "foo") は c:\foo ではなく、ドライブ C: のカレントディレクトリからの相対パス (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)¶

指定されたファイル名の正規のパスを返します。パスに含まれるシンボリックリンクは解決されます (オペレーティングシステムがサポートしている場合)。 Windows では、C:\\PROGRA~1 のような MS-DOS 形式 (8.3 形式とも呼びます) の名前も C:\\Program Files に解決します。返されるパスの大文字・小文字はオペレーティングシステムが返す表記を使うため、path の表記と異なる場合があります。特にドライブレターは大文字になります。

デフォルトでは、パスの各要素を順に評価し、存在しない要素、シンボリックリンクのループ、または評価時に OSError を送出する要素に到達すると停止します。そのような要素以降は、パスの既存の部分に変更せずに追加します。

このように処理するエラーには「アクセスが拒否された」「ディレクトリでない」「内部関数の引数が不正」などがあります。そのため、結果のパスは存在しなかったり、アクセスできなかったり、リンクやループをまだ含んでいたり、ディレクトリでないものを経由したりする場合があります。

この動作はキーワード引数で変更できます:

strict が True の場合、パスの評価中に最初に発生したエラーを再送出します。具体的には、path が存在しない場合は FileNotFoundError を、その他の理由でアクセスできない場合は別の OSError を送出します。 strict が ALL_BUT_LAST の場合、パスの最後の要素は存在しなくても構いませんが、他のすべてのエラーは送出します。

strict が os.path.ALLOW_MISSING の場合、strict=True と同様に、FileNotFoundError 以外のエラーを再送出します。そのため、返されたパスにはシンボリックリンクは含まれませんが、指定されたファイルやその親ディレクトリの一部は存在しない場合があります。

注釈

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

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

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

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

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

バージョン 3.15 で変更: strict パラメータに ALL_BUT_LAST と ALLOW_MISSING の値が追加されました。

os.path.ALL_BUT_LAST¶: realpath() の strict 引数に使う特別な値。

Added in version 3.15.

os.path.ALLOW_MISSING¶: realpath() の strict 引数に使う特別な値。

Added in version 3.15.

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, /)¶: パス名 path を (head, tail) のペアに分割します。 tail はパス名の最後の要素で、head はそれより前のすべての部分です。 tail にスラッシュが含まれることはありません。 path がスラッシュで終わる場合、tail は空になります。 path にスラッシュがない場合、head は空になります。 path が空の場合は head と tail の両方が空になります。 head がルート (1 つ以上のスラッシュのみ) でない限り、末尾のスラッシュを取り除きます。いずれの場合も join(head, tail) は path と同じ場所へのパスを返しますが、文字列としては異なる場合があります。 join()、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 が相対パスの場合)、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 になります。

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

前のトピックへ

次のトピックへ

このページ

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

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