小さなスクリプトを書いていると、ファイルの保存先やAPIのURLといった値をコードの先頭に並べたくなりますよね。最初はそれで十分です。
ところが、同じスクリプトを別のパソコンや本番サーバーで動かそうとした途端、困ったことが起きます。値を変えるたびにコードそのものを書き換えることになるからです。
そんなときに役立つのが、設定を別のファイルに分けておくやり方です。Pythonには、そのための形式としてTOMLを読み込むtomllibというモジュールが標準で入っています。
今回は、TOMLとはどんな形式なのかという話から始めて、tomllibの使い方と実務での注意点までを見ていきましょう。
TOMLは、人が読み書きしやすい設定ファイルの形式¶
TOMLは、設定ファイルを書くために作られたテキスト形式です。名前は作者の名前を取ったTom's Obvious, Minimal Languageの頭文字から来ています。
見た目はとてもシンプルです。キーと値をイコールでつなぎ、角かっこでグループの名前を書くだけで、階層のある設定を表現できます。
まずは、アプリの設定を想定した小さなTOMLファイルを見てみましょう。ここではconfig.tomlという名前で保存したとします。
# アプリ全体の設定
app_name = "sales-report"
debug = false
max_retry = 3
[database]
host = "localhost"
port = 5432
tables = ["users", "orders"]
[report]
start_date = 2026-04-01
output_dir = "reports"
シャープから始まる行はコメントです。JSONと違ってコメントを書けるので、この値はなぜこうしたのか、というメモを設定ファイルの中に残せます。
文字列はダブルクォートで囲み、数値や真偽値はそのまま書きます。日付をクォートなしで書ける点も、TOMLの大きな特徴です。
Pythonのプロジェクトでよく見かけるpyproject.tomlも、このTOML形式で書かれています。プロジェクト管理の文脈でのTOMLについては、こちらで詳しく解説しています。【関連記事】pyproject.tomlとは？これからのPythonプロジェクト管理入門
tomllibは、Python 3.11から使える標準ライブラリ¶
tomllibは、TOMLを読み込むためのモジュールです。PEP 680という提案をもとに、Python 3.11で標準ライブラリに加わりました。
それまでは、TOMLを読みたければtomliやtomlといった外部ライブラリをpipで入れる必要がありました。tomllibは、そのうちのtomliをもとにして作られています。
標準ライブラリに入ったきっかけのひとつは、pyproject.tomlの普及です。パッケージをビルドするツール自身がTOMLを読む必要があるのに、そのためのライブラリを先にインストールしなければならない。そんな鶏と卵のような問題を解消する狙いがありました。
では、先ほどのconfig.tomlを実際に読み込んでみましょう。コードはたったこれだけです。
import tomllib
with open("config.toml", "rb") as f:
config = tomllib.load(f)
print(config["app_name"]) # sales-report
print(config["database"]["port"]) # 5432
print(config["database"]["tables"]) # ['users', 'orders']
print(config["report"]["start_date"]) # 2026-04-01
読み込んだ結果は、ふつうの辞書になります。角かっこで書いたdatabaseのようなグループは、辞書の中の辞書として入っています。
辞書の扱いに自信がない方は、先にこちらを読んでおくとスムーズです。【関連記事】PythonでJSONデータの扱いをマスター！API連携に必須のjsonモジュールの使い方
loadとloadsの違いを押さえよう¶
tomllibの関数は、実は2つしかありません。ファイルから読むload関数と、文字列から読むloads関数です。
jsonモジュールと同じ命名です。両者の違いを表で整理しておきましょう。
| 関数 | 受け取るもの | 主な使いどころ |
|---|---|---|
| tomllib.load(fp) | バイナリモードで開いたファイル | 設定ファイルを読むとき |
| tomllib.loads(s) | 文字列 | テストや、別の場所から受け取ったTOMLを読むとき |
どちらも戻り値は辞書です。loadsは、テストコードの中でちょっとしたTOMLを試したいときに便利ですよ。
import tomllib
text = """
title = "テスト"
numbers = [1, 2, 3]
"""
data = tomllib.loads(text)
print(data) # {'title': 'テスト', 'numbers': [1, 2, 3]}
なぜrbで開かなければいけないのか¶
先ほどのコードで、openの第2引数が"r"ではなく"rb"になっていたことに気づいたでしょうか。ここは、多くの人が最初につまずくところです。
試しに"r"で開いたファイルを渡すと、次のようなエラーになります。
import tomllib
with open("config.toml", "r") as f:
config = tomllib.load(f)
# TypeError: File must be opened in binary mode, e.g. use `open('foo.toml', 'rb')`
rbはバイナリモードといって、ファイルの中身を文字に変換せず、バイトのまま読み込む開き方です。TOMLの仕様では、ファイルはUTF-8で書くことになっています。
テキストモードで開くと、パソコンの環境によってはUTF-8以外の文字コードで読まれてしまうことがあります。そこでtomllibは、バイトのまま受け取って自分でUTF-8として読む方式を選んでいます。
私は10年ほどエンジニアとして開発してきましたが、WindowsとMacで同じファイルを読んだら片方だけ文字化けした、という調査に半日使ったことがあります。最初から文字コードを固定してくれるこの設計は、地味ですがありがたいものです。
文字コードや文字化けの仕組みについては、こちらで詳しく解説しています。【関連記事】Pythonの文字コードとは？文字化けとUnicodeDecodeErrorの直し方を初心者向けに解説
日付や数値はどんな型になるのか¶
TOMLの値は、読み込むとPythonの型に変換されます。どの値が何になるのかを知っておくと、あとで型の違いに悩まされずに済みます。
主な対応を表にまとめました。
| TOMLの値 | 書き方の例 | Pythonの型 |
|---|---|---|
| 文字列 | "hello" | str |
| 整数 | 42 | int |
| 小数 | 3.14 | float |
| 真偽値 | true / false | bool |
| 配列 | [1, 2, 3] | list |
| テーブル | [database] | dict |
| 日付 | 2026-04-01 | datetime.date |
| 時刻 | 07:32:00 | datetime.time |
| 日時 | 2026-04-01T09:00:00+09:00 | datetime.datetime |
うれしいのは、日付が最初からdatetime.dateとして手に入ることです。JSONだと日付は文字列になるので、自分で変換するひと手間がかかります。
小数を正確に扱いたいときはparse_float¶
TOMLの小数は、そのままだとfloatとして読み込まれます。多くの場面ではそれで問題ありません。
ただ、金額や税率のように誤差が許されない値を設定ファイルに書く場合は、少し注意が必要です。floatは0.1のような値を正確に表せないからです。
そんなときは、load関数やloads関数のparse_floatという引数を使います。小数をどの型に変換するかを、自分で指定できる仕組みです。
import tomllib
from decimal import Decimal
text = "tax_rate = 0.1"
data = tomllib.loads(text, parse_float=Decimal)
print(data["tax_rate"]) # 0.1
print(type(data["tax_rate"])) # <class 'decimal.Decimal'>
Decimalを指定すると、設定ファイルに書いた数字がそのまま正確な小数として入ります。floatで読んでからDecimalに変換するより安全です。
Decimalがなぜお金の計算に向いているのかは、こちらで詳しく解説しています。【関連記事】Pythonのdecimalとは？お金の計算でfloatを使ってはいけない理由を初心者向けに解説
書き込みはできない、という割り切り¶
ここまで読んで、設定を書き換えて保存するにはどうするのだろう、と思った方もいるかもしれません。実は、tomllibには書き込みの機能がありません。
これは作り忘れではなく、意図的な判断です。PEP 680では、TOMLはあくまで人が書く設定ファイルの形式であり、プログラムからデータを保存するための形式ではない、と説明されています。
書き込みの機能を入れると、コメントや書式をどう保つかといった難しい問題も抱えることになります。いったん標準ライブラリに入れた機能はあとから消しにくいので、まずは読み込みだけに絞った、というわけです。
それでもTOMLを書き出したい場合は、tomli-wという外部ライブラリがあります。tomliと同じ作者によるもので、pipでインストールして使います。
書き間違いはTOMLDecodeErrorで受け止める¶
設定ファイルは人が手で書くものなので、書き間違いは必ず起こります。クォートの閉じ忘れや、イコールの後ろの値の書き忘れなどです。
TOMLとして正しくない内容を読み込むと、tomllibはTOMLDecodeErrorという例外を出します。これはValueErrorの仲間なので、次のように受け止められます。
import sys
import tomllib
def load_config(path):
try:
with open(path, "rb") as f:
return tomllib.load(f)
except FileNotFoundError:
sys.exit(f"設定ファイルが見つかりません: {path}")
except tomllib.TOMLDecodeError as e:
sys.exit(f"設定ファイルの書き方に誤りがあります: {e}")
config = load_config("config.toml")
retry = config.get("max_retry", 3)
print(retry)
ファイルがない場合と、書き方が間違っている場合を分けておくのがポイントです。どちらの問題なのかがメッセージですぐにわかります。
実務でありがちなのは、設定の読み込みに失敗したまま処理が進み、ずっと後ろのほうで意味のわからないエラーになるケースです。私も以前、設定のキー名のタイプミスに気づかず、夜間バッチが既定値のまま動き続けていたことがありました。起動したらまず設定を読み、おかしければその場で止める。これを習慣にするだけで、トラブルの調査がぐっと楽になります。
JSONやINIとどう使い分ける？¶
設定ファイルの形式は、TOMLのほかにもいくつかあります。Pythonの標準ライブラリで読めるものを比べてみましょう。
| 形式 | 読み込むモジュール | コメント | 日付の型 | 向いている用途 |
|---|---|---|---|---|
| TOML | tomllib | 書ける | そのまま扱える | 人が書く設定ファイル |
| JSON | json | 書けない | 文字列になる | APIとのデータのやりとり |
| INI | configparser | 書ける | 文字列になる | 古くからある単純な設定 |
JSONは、プログラム同士でデータをやりとりするのに向いた形式です。ただ、コメントが書けず、最後の要素の後ろにカンマを付けるとエラーになるなど、人が手で書くには少し窮屈です。
INIファイルはconfigparserで読めますが、値はすべて文字列として扱われます。数値や真偽値が欲しい場合は、自分で変換する手間がかかります。
パスワードやAPIキーは別に管理する¶
ひとつ注意しておきたいのは、秘密の情報の扱いです。TOMLファイルは読みやすい反面、誰でも中身を見られるテキストでもあります。
パスワードやAPIキーまでconfig.tomlに書いてGitにコミットしてしまうと、情報が漏れる原因になります。秘密の値は環境変数で渡し、TOMLには公開しても困らない設定だけを書くのが基本です。
環境変数の扱い方は、こちらで詳しく解説しています。【関連記事】環境変数とは？PythonでAPIキーを安全に扱う.envと os.environ の基本を初心者向けに解説
Python 3.11より前の環境で使いたいとき¶
tomllibはPython 3.11からの機能なので、それより古いPythonにはありません。古いバージョンでimportすると、ModuleNotFoundErrorになります。
もし古い環境にも対応したいなら、tomllibのもとになったtomliをpipで入れるのが定番です。使い方はほぼ同じなので、次のように書くと両方の環境で動きます。
import sys
if sys.version_info >= (3, 11):
import tomllib
else:
import tomli as tomllib
名前をtomllibにそろえておけば、そのあとのコードは書き換えずに済みます。
また、リリース候補版が出ているPython 3.15では、tomllibがTOML 1.1.0に対応すると告知されています。インラインテーブルの中で改行や末尾のカンマが使えるようになるなど、書き方が少し柔軟になる予定です。
TOML 1.0.0で正しく書かれたファイルは、これまでと同じように読めるとされています。今ある設定ファイルが急に読めなくなる心配はありません。
まとめ¶
今回は、Pythonの標準ライブラリtomllibの使い方を見てきました。ポイントを振り返っておきましょう。
tomllibを使えば、Python 3.11以降ならインストールなしでTOMLの設定ファイルを辞書として読み込めます。ファイルは必ずrbで開くこと、日付はそのままdatetimeの型で手に入ることを覚えておけば、まず困りません。
あわせて、tomllibは読み込み専用だという点も押さえておきましょう。書き出しが必要ならtomli-wを使い、秘密の値は環境変数で渡すのが実務での定番です。
設定をコードから切り離すと、同じスクリプトを別の環境でも気軽に動かせるようになります。まずは手元のスクリプトの定数を、ひとつだけconfig.tomlに移すところから試してみてください。
ここまでお読みいただきありがとうございました。
