2025.12.25

【Python】tomllibでTOMLファイルを読み込む方法

naoki-hn

Python で TOML ファイルを読み込む際に使用する tomllib の基本的な使い方について解説します。

`tomllib` での TOML ファイルの読み込み

TOML ファイルは、Tom’s Obvious, Minimal Language という設定ファイルフォーマットの 1 種です。Tom というのは、開発者の Tom Preston-Werner 氏からとられています。名称にもあるようにミニマルであることを目指して開発されています。

TOML ファイルは以下のような形式のファイルです。

[DB_SERVER]
HOST = "192.168.1.200"
PORT = 3306

[WEB_SERVER]
HOST = "192.168.1.100"
PORT = 80

セクションは [] で表すことができ、数値はそのまま書けますが、文字列は必ずクォート (") で囲う必要があります。

TOML ファイルは、人が読み書きしやすいような構造となっており、プログラムでも安全に解析できます。Python では、PEP 517 / 518 で pyproject.toml が導入されプロジェクト設定や依存関係、ツール設定を一元化する役割を担っています。

Python の設定ファイル管理では、古くからは INI ファイルが使われており、その後は、インフラや各種ツール設定を中心に YAML ファイルが広く使用されていますが、pyproject.toml の導入をきっかけにプロジェクトや開発ツール設定としてTOMLファイルの利用が急速に増えてきています。

Python では以前は toml や tomli といった外部ライブラリが採用されていましたが、Python 3.11 より tomllib として標準ライブラリ化されたため、簡単に使用することができます。なお、tomli は tomllib の実装のベースとなっています。

この記事では、tomllib を使って TOML ファイルを扱う方法を紹介します。

YAML ファイルや INI ファイルの Python での扱い方については、以下を参考にしてください。

`tomllib` の基本的な使い方（読み込み）

tomllib は TOML ファイルの安全な読み込みを目的とした標準ライブラリであり、書き込み機能は提供されていません。もともと TOML ファイルは、人が手で直す設定ファイル用途前提であり、tomllib は安全に読むことに責務を限定しています。

公式ドキュメントで、Tomli-W や tomlkit といった書き込み用ライブラリも参考に紹介されていますが、本記事では紹介は省略します。

tomllib を使用した TOML ファイルの読み込みは以下のようにします。config.toml というファイルを用意して読み込んでいます。

config.toml

[WEB_SERVER]
HOST = "192.168.1.100"
PORT = 80

[DB_SERVER]
HOST = "192.168.1.200"
PORT = 3306

tomllib_basic.py

import tomllib

# TOMLファイルの読み込み
with open("config.toml", "rb") as f:
    config = tomllib.load(f)

# 読み込んだデータの型を確認
print(type(config))

# 読み込んだ値の参照
print(config["WEB_SERVER"])
print(config["WEB_SERVER"]["HOST"])
print(config["WEB_SERVER"]["PORT"])

print(config["DB_SERVER"])
print(config["DB_SERVER"]["HOST"])
print(config["DB_SERVER"]["PORT"])

【実行結果】
<class 'dict'>
{'HOST': '192.168.1.100', 'PORT': 80}
192.168.1.100
80
{'HOST': '192.168.1.200', 'PORT': 3306}
192.168.1.200
3306

TOML ファイルの読み込みを行う場合には、tomllib.load 関数を使用します。ファイルはバイナリモード（"rb"）で open したオブジェクトを指定します。

"r" 開いたオブジェクトでもいいかと思うかもしれませんが、"r" とした場合には以下の TypeError となります。

TypeError: File must be opened in binary mode, e.g. use `open('foo.toml', 'rb')`

これは、TOML が UTF-8 固定の仕様であり、文字コード処理をライブラリ側で一貫して行うためです。

まとめ

Python で TOML ファイルを読み込む際に使用する tomllib の基本的な使い方について解説しました。

TOML は、Python におけるプロジェクト定義の pyproject.toml で使用されており、もちろん他の設定ファイル管理にも使用ができます。Python 3.11 からは、tomllib として標準ライブラリ化したため、より使用しやすくなりました。

tomllib は人が手で直す設定ファイル用途前提であり、TOML ファイルの安全な読み込みを目的とした標準ライブラリであるため、書き込み機能は提供されていない点には注意が必要です。この記事では取り上げていませんが、公式ドキュメントで、Tomli-W や tomlkit といったライブラリが紹介されているので必要に応じて確認してください。

tomllib を使って TOML ファイルを有効活用してもらえたらと思います。

tomllib の公式ドキュメントはこちらを参照してください。

ソースコード

上記で紹介しているソースコードについては GitHub にて公開しています。参考にしていただければと思います。

tomllib での TOML ファイルの読み込み

tomllib の基本的な使い方（読み込み）

まとめ

`tomllib` での TOML ファイルの読み込み

`tomllib` の基本的な使い方（読み込み）