Pythonのloggingの使い方|printから卒業するログ出力の基本と設定例
プログラムの動きを確かめるとき、とりあえず print() を書き足していませんか。動作確認の間はそれで十分ですが、本番で動かすスクリプトやサーバーの処理では、「いつ」「どこで」「どのくらい重大なことが」起きたのかを後から追えるように、logging モジュールでログを残すのが基本です。
この記事では、print との違い、ログレベル、basicConfig、logging.getLogger(__name__)、画面とファイルへの同時出力、RotatingFileHandler、logger.exception、よくある間違いを順に説明します。出力は Windows 11・Python 3.12.6 で実際に実行したもので、仕様は Python 公式ドキュメント(Logging HOWTO と logging モジュールのリファレンスの英語原文)で確認しました。
logging とは?print との違い
ログは、プログラムが動いている間に起きたことの記録です。print と比べると、次のような違いがあります。
| print() | logging | |
|---|---|---|
| 出力先 | 標準出力(stdout) | 既定は標準エラー出力(stderr)。ファイルなどにも出せる |
| 重要度の区別 | なし | DEBUG・INFO・WARNING・ERROR・CRITICAL の 5 段階 |
| 表示する・しないの切り替え | print の行を消す・コメントにするしかない | 設定 1 か所で「INFO 以上だけ出す」などと切り替えられる |
| 日時・発生場所 | 自分で書き足す | 書式を決めておけば自動で付く |
公式の Logging HOWTO でも、コマンドラインのプログラムがふつうの結果を画面に出すなら print()、プログラムの通常の動きを記録するならロガーの info()(細かい調査用なら debug())、と使い分けが示されています。print をやめる必要はなく、利用者に見せる「結果」は print、開発者や運用担当が後で読む「記録」は logging と分けるのが基本です。
出力先が違うことを確かめる
次のコードを sample.py として保存します(basicConfig は後で説明します)。
import logging
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)
print("結果: 42")
logger.info("計算が終わりました")
PowerShell で、sample.py を保存したフォルダーに移動してから、出力を out.txt に保存する形で実行します。
py sample.py > out.txt
画面には次の 1 行だけが残り、out.txt には 結果: 42 だけが入りました。> で保存されるのは標準出力だけなので、標準エラー出力に出たログは画面に残ったわけです。結果をファイルに保存したり、ほかのコマンドに渡したりしても、ログが混ざりません。
INFO:__main__:計算が終わりました
ログレベル:DEBUG〜CRITICAL の 5 段階
logging では、1 つ 1 つのログにレベル(重要度)を付けます。レベルには数値があり、設定したレベル以上のものだけが出力されます。意味は公式ドキュメントの説明を訳したものです。
| レベル | 数値 | 意味 | 使う場面の例 |
|---|---|---|---|
| DEBUG | 10 | 細かい情報。ふつうは問題を調べるときだけ必要 | 変数の中身、読み込んだ件数 |
| INFO | 20 | 想定どおりに動いていることの確認 | 処理の開始・終了、接続できた |
| WARNING | 30 | 想定外のことが起きた、または近いうちに問題が起きそう。プログラムは想定どおり動いている | ディスクの空きが少ない、設定がないので既定値を使う |
| ERROR | 40 | より深刻な問題で、ある機能を実行できなかった | ファイルを保存できなかった |
| CRITICAL | 50 | 深刻なエラー。プログラム自体が続けられないかもしれない | データベースにつながらず起動できない |
大事なのは、何も設定しないと WARNING 以上しか出ないことです。公式ドキュメントにも「既定のレベルは WARNING」と書かれています。5 つのレベルで 1 行ずつ出してみます。
import logging
logging.debug("デバッグ用の細かい情報")
logging.info("処理を開始しました")
logging.warning("ディスクの空きが少なくなっています")
logging.error("ファイルを保存できませんでした")
logging.critical("処理を続けられません")
実行結果です。debug と info の行は出力されません。
WARNING:root:ディスクの空きが少なくなっています
ERROR:root:ファイルを保存できませんでした
CRITICAL:root:処理を続けられません
何も設定しないときの書式は「レベル名:ロガー名:メッセージ」です。root は、すべてのロガーの親になるルートロガーの名前です。logging.info() のようにモジュールの関数を直接呼ぶと、このルートロガーに記録されます。
basicConfig で表示レベル・書式・出力先を決める
logging.basicConfig() は、ルートロガーの設定をまとめて行う関数です。小さなスクリプトなら、これを 1 回呼ぶだけで足ります。プログラムの最初のほうで、ログを出す前に呼ぶのが決まりです。
import logging
logging.basicConfig(
level=logging.DEBUG,
format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
datefmt="%Y-%m-%d %H:%M:%S",
)
logging.debug("デバッグ用の細かい情報")
logging.info("処理を開始しました")
logging.warning("ディスクの空きが少なくなっています")
実行結果です。日時は実行した時刻によって変わります。level を DEBUG にしたので、debug と info の行も出るようになりました。
2026-10-18 14:19:12 [DEBUG] root: デバッグ用の細かい情報
2026-10-18 14:19:12 [INFO] root: 処理を開始しました
2026-10-18 14:19:12 [WARNING] root: ディスクの空きが少なくなっています
basicConfig でよく使う引数は次のとおりです。
| 引数 | 意味 | 例 |
|---|---|---|
| level | このレベル以上を出す | logging.INFO |
| format | 1 行の書式。省略すると「レベル名:ロガー名:メッセージ」 | "%(asctime)s %(message)s" |
| datefmt | %(asctime)s の日時の書式(time.strftime と同じ指定) | "%Y-%m-%d %H:%M:%S" |
| filename | 画面ではなくこのファイルに書く | "app.log" |
| filemode | filename を開くモード。既定は追記の "a" | "w"(毎回上書き) |
| encoding | filename のファイルの文字コード(Python 3.9 で追加) | "utf-8" |
| force | True なら、それまでの設定を消して設定し直す(Python 3.8 で追加) | True |
datefmt を省略すると、%(asctime)s は 2026-10-18 14:20:18,174 のように「,」の後にミリ秒が付いた形になります。datefmt に使える %Y・%m などの書式は「Pythonのdatetimeの使い方」の strftime の表と同じです。
format でよく使う項目
format の中には、%(項目名)s の形で次のような情報を入れられます。%(lineno)d だけは数値なので末尾が d です。
| 書き方 | 入るもの |
|---|---|
%(asctime)s | 日時 |
%(levelname)s | レベル名(INFO など) |
%(name)s | ロガーの名前 |
%(message)s | ログの本文 |
%(filename)s | ログを出したファイル名 |
%(lineno)d | ログを出した行番号 |
%(funcName)s | ログを出した関数名 |
たとえば format を "%(asctime)s %(levelname)s %(filename)s:%(lineno)d %(funcName)s() %(message)s" にして、app.py の 11 行目にある load 関数の中でログを出すと、2026-10-18 14:20:18,174 INFO app.py:11 load() 読み込みます のように出力されました(日時は実行時刻で変わります)。
ファイルに書く:filename と encoding
filename を指定すると、画面ではなくファイルに書かれます。日本語を書くなら encoding=”utf-8″ を必ず付けます。
import logging
logging.basicConfig(
filename="app.log",
encoding="utf-8",
level=logging.INFO,
format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
datefmt="%Y-%m-%d %H:%M:%S",
)
logger = logging.getLogger(__name__)
logger.info("処理を開始しました")
logger.warning("設定ファイルがないので既定値を使います")
実行しても画面には何も出ず、同じフォルダーに app.log ができます。中身は次のとおりです(日時は実行時刻で変わります)。filemode の既定は追記なので、もう一度実行すると行が増えていきます。
2026-10-18 14:19:42 [INFO] __main__: 処理を開始しました
2026-10-18 14:19:42 [WARNING] __main__: 設定ファイルがないので既定値を使います
encoding を省くと、open() の既定の文字コードで書かれます。日本語版 Windows の Python 3.12 で試すと app.log は Shift_JIS(cp932)になり、UTF-8 として読むとエラーになりました。Linux のサーバーや UTF-8 前提のツールでは文字化けします。詳しくは「Pythonのファイル読み書き」で説明しています。encoding 引数は Python 3.9 で追加されたので、3.8 以前では使えません。
logger = logging.getLogger(__name__) を使う
ここまでの例でも出てきたように、実際のプログラムでは logging.info() を直接呼ぶのではなく、各ファイル(モジュール)の先頭でロガー(ログを受け付ける窓口)を作って使います。公式ドキュメントでも、特別な理由がない限り __name__ を使うことが勧められています。
__name__ には、そのファイルのモジュール名が入ります。実行したファイルなら __main__、import された tax.py なら tax です。2 つのファイルで試します。まず tax.py です。
import logging
logger = logging.getLogger(__name__)
def with_tax(price):
total = int(price * 1.1)
logger.info("税込み価格を計算しました: %s円 -> %s円", price, total)
return total
同じフォルダーに main.py を作ります。
import logging
import tax
logger = logging.getLogger(__name__)
logging.basicConfig(
level=logging.INFO,
format="%(asctime)s %(levelname)-8s %(name)s: %(message)s",
)
logger.info("アプリを起動しました")
print(tax.with_tax(1000))
py main.py
実行結果です(日時は実行時刻で変わります)。最後の 1100 は print の出力です。%(levelname)-8s は「8 文字分の幅で左寄せ」の意味で、列がそろいます。
2026-10-18 14:19:24,993 INFO __main__: アプリを起動しました
2026-10-18 14:19:24,993 INFO tax: 税込み価格を計算しました: 1000円 -> 1100円
1100
ロガー名で、どのファイルから出たログかがすぐ分かります。設定(basicConfig)は main.py で 1 回だけ行い、tax.py ではロガーを作って使うだけです。tax のロガーのログは親のルートロガーに渡され、その設定で出力されます。
画面とファイルの両方に出す:Handler と Formatter
「画面には INFO 以上、ファイルには DEBUG も含めてすべて」のように、出力先ごとに設定を変えたいときは、basicConfig ではなく部品を組み合わせて設定します。登場する部品は次の 3 つです。
| 部品 | 役割 | 例 |
|---|---|---|
| Logger(ロガー) | ログを受け付ける窓口 | logging.getLogger(__name__) |
| Handler(ハンドラー) | ログをどこへ出すか | StreamHandler(画面)、FileHandler(ファイル) |
| Formatter(フォーマッター) | どんな書式で出すか | logging.Formatter("%(asctime)s %(message)s") |
1 つのロガーに複数のハンドラーを付けると、同じログが複数の出力先に送られます。ハンドラーごとにレベルを決められるので、出力先によって量を変えられます。
import logging
logger = logging.getLogger(__name__)
logger.setLevel(logging.DEBUG)
formatter = logging.Formatter(
"%(asctime)s [%(levelname)s] %(name)s: %(message)s",
datefmt="%Y-%m-%d %H:%M:%S",
)
# コンソール:INFO 以上
console = logging.StreamHandler()
console.setLevel(logging.INFO)
console.setFormatter(formatter)
logger.addHandler(console)
# ファイル:DEBUG 以上(すべて)
file_handler = logging.FileHandler("app.log", encoding="utf-8")
file_handler.setLevel(logging.DEBUG)
file_handler.setFormatter(formatter)
logger.addHandler(file_handler)
logger.debug("読み込んだ件数: %d", 120)
logger.info("処理を開始しました")
logger.error("保存に失敗しました")
画面に出た内容です(日時は実行時刻で変わります)。
2026-10-18 14:19:42 [INFO] __main__: 処理を開始しました
2026-10-18 14:19:42 [ERROR] __main__: 保存に失敗しました
app.log の中身です。DEBUG の行はファイルにだけ入りました。
2026-10-18 14:19:42 [DEBUG] __main__: 読み込んだ件数: 120
2026-10-18 14:19:42 [INFO] __main__: 処理を開始しました
2026-10-18 14:19:42 [ERROR] __main__: 保存に失敗しました
logger.setLevel(logging.DEBUG) を忘れないでください。ロガーで落とされたログはハンドラーまで届きません。自分で作ったロガーはレベルが未設定(NOTSET)で、親をたどってルートロガーのレベル(既定は WARNING)が使われるため、この行がないと debug と info は出ません。
ログファイルが大きくなりすぎないようにする:RotatingFileHandler
FileHandler は 1 つのファイルに書き足し続けるので、何か月も動かすとログファイルが巨大になります。RotatingFileHandler を使うと、決めたサイズに近づいたところでファイルを切り替え(ローテーション)、古いファイルを決めた数だけ残せます。
import logging
from logging.handlers import RotatingFileHandler
logger = logging.getLogger(__name__)
logger.setLevel(logging.INFO)
handler = RotatingFileHandler(
"app.log",
maxBytes=200, # 200 バイトを超えそうになったら切り替える(説明用に小さくしている)
backupCount=2, # 古いファイルは 2 つまで残す
encoding="utf-8",
)
handler.setFormatter(logging.Formatter("%(asctime)s %(message)s"))
logger.addHandler(handler)
for i in range(1, 11):
logger.info("%d 件目の処理が終わりました", i)
10 行書いたあと、フォルダーには app.log・app.log.1・app.log.2 の 3 つができました。中身は次のとおりです(日時は実行時刻で変わります)。1 行は 64 バイトなので、3 行ごとに切り替わっています。
--- app.log.2
2026-10-18 14:19:42,228 4 件目の処理が終わりました
2026-10-18 14:19:42,230 5 件目の処理が終わりました
2026-10-18 14:19:42,230 6 件目の処理が終わりました
--- app.log.1
2026-10-18 14:19:42,230 7 件目の処理が終わりました
2026-10-18 14:19:42,230 8 件目の処理が終わりました
2026-10-18 14:19:42,230 9 件目の処理が終わりました
--- app.log
2026-10-18 14:19:42,230 10 件目の処理が終わりました
1〜3 件目は消えています。書き込み先は常に app.log で、いっぱいになると app.log → app.log.1 → app.log.2 と名前がずれ、backupCount を超えた古いファイルは削除されます。公式ドキュメントによると、maxBytes と backupCount のどちらかが 0 だとローテーションは起きません(どちらも既定は 0)。実際には maxBytes を数 MB(例:5 * 1024 * 1024)にします。
「毎日 0 時に切り替える」のように時間で区切るなら TimedRotatingFileHandler を使います。
logger.exception で例外のトレースバックを残す
except で例外を受け止めて処理を続けるときは、logger.exception() を使うと、ERROR レベルのログと一緒にトレースバック(どのファイルの何行目で、どんな順番で関数が呼ばれてエラーになったか)が記録されます。公式ドキュメントにあるとおり、except の中で呼ぶためのメソッドです。
import logging
logging.basicConfig(
level=logging.INFO,
format="%(asctime)s [%(levelname)s] %(message)s",
)
logger = logging.getLogger(__name__)
def divide(a, b):
return a / b
try:
divide(10, 0)
except ZeroDivisionError:
logger.exception("割り算に失敗しました")
try:
divide(10, 0)
except ZeroDivisionError as e:
logger.error("割り算に失敗しました: %s", e)
print("処理を続けます")
実行結果です。日時は実行時刻で変わり、ファイルの場所は環境によって変わります(ここでは「C:\…\app.py」と省略しています)。
2026-10-18 14:20:18,252 [ERROR] 割り算に失敗しました
Traceback (most recent call last):
File "C:\…\app.py", line 15, in <module>
divide(10, 0)
File "C:\…\app.py", line 11, in divide
return a / b
~~^~~
ZeroDivisionError: division by zero
2026-10-18 14:20:18,255 [ERROR] 割り算に失敗しました: division by zero
処理を続けます
logger.error でメッセージだけを残すと、どこで起きたかが分かりません。原因を調べるには logger.exception のトレースバックが役立ちます。どちらもプログラムは止まらず、最後の print まで進んでいます。トレースバックの読み方は「Pythonの例外処理入門」で説明しています。
ログに個人情報やパスワードを出さない
ログファイルは、障害の調査で多くの人が読んだり、ログを集めるサービスに送られたりします。パスワード・API キー・トークン・クレジットカード番号・個人情報をログに書くと、そこから漏れるおそれがあります。特に、辞書やオブジェクトを丸ごと出すと、気づかないうちに秘密の値が入ります。
import logging
logging.basicConfig(level=logging.INFO, format="[%(levelname)s] %(message)s")
logger = logging.getLogger(__name__)
user = {"id": 1024, "email": "taro@example.com", "password": "P@ssw0rd"}
# 悪い例:辞書をまるごと出すとパスワードもログに残る
logger.info("ログイン要求: %s", user)
# よい例:必要な項目だけを出す
logger.info("ログイン要求: user_id=%s", user["id"])
実行結果です。1 行目にはパスワードがそのまま記録されています。
[INFO] ログイン要求: {'id': 1024, 'email': 'taro@example.com', 'password': 'P@ssw0rd'}
[INFO] ログイン要求: user_id=1024
ログに出すのは、調査に必要な最小限の情報(ユーザー ID、件数、処理の名前など)にとどめます。DEBUG レベルなら出してもよい、という考え方も危険です。設定を変えれば DEBUG も記録されるので、レベルに関係なく秘密の値は出さないようにします。パスワードの扱い方そのものは「パスワードの安全な保存方法」も参考にしてください。
よくある間違い
basicConfig が 2 回目以降効かない
公式ドキュメントによると、basicConfig はルートロガーにすでにハンドラーがあると何もしません(force=True のときを除く)。
import logging
logging.basicConfig(level=logging.WARNING)
logging.basicConfig(level=logging.DEBUG) # 2 回目は無視される
logging.debug("表示されない")
logging.basicConfig(level=logging.DEBUG, force=True)
logging.debug("force=True なら表示される")
実行結果です。2 回目の basicConfig は効かず、force=True を付けたあとのログだけが出ました。
DEBUG:root:force=True なら表示される
気づきにくいのが、basicConfig より前に logging.info() などを呼んでしまう場合です。ルートロガーにハンドラーがないときに logging.info() などのモジュールの関数を呼ぶと、内部で引数なしの basicConfig() が自動で呼ばれます。その後に書いた basicConfig は無視されます。
import logging
logging.info("設定を読み込みます") # basicConfig より前に呼んでしまった
logging.basicConfig(
level=logging.INFO,
format="%(asctime)s [%(levelname)s] %(message)s",
)
logging.info("処理を開始しました")
logging.warning("警告です")
実行結果です。level も format も効かず、既定の WARNING・既定の書式のままでした。
WARNING:root:警告です
import したライブラリが先にログの設定をしている場合も同じことが起きます。basicConfig はメインのファイルの、ほかの処理より前で 1 回だけ呼ぶようにし、それでも効かないときは原因を探したうえで force=True を検討します。
ルートロガーを直接使う
logging.info() のようにルートロガーを直接使うと、すべてのログのロガー名が root になり、どのファイルから出たログか分からなくなります。上で見たように、設定が効かなくなる原因にもなります。公式ドキュメントも、ライブラリではルートロガーにログを出さないよう強く勧めています。各ファイルで logger = logging.getLogger(__name__) を作って使う習慣にしましょう。
f 文字列で書くと、出さないログの文字列も作られる
ログのメッセージは、f 文字列ではなく logger.debug("データ: %s", data) のように %s と引数で書くのが logging の流儀です。公式ドキュメントによると、%s 形式の組み立て(フォーマット)は、本当に出力するときまで行われません。f 文字列は logger.debug を呼ぶ前に文字列が作られるので、出力されないログでも組み立ての手間がかかります。
文字列にする処理(__str__)が呼ばれたときに印を出すクラスで確かめます。レベルは INFO なので、debug のログはどちらも出力されません。
import logging
class Slow:
def __str__(self):
print(" ← __str__ が呼ばれた")
return "重い文字列"
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)
data = Slow()
print("f 文字列:")
logger.debug(f"データ: {data}")
print("%s 形式:")
logger.debug("データ: %s", data)
print("終わり")
実行結果です。f 文字列のほうだけ、捨てられるログのために __str__ が呼ばれました。
f 文字列:
← __str__ が呼ばれた
%s 形式:
終わり
ループの中の debug ログや、大きなデータを文字列にするログでは差が出ます。なお、引数そのものの計算(関数の呼び出しなど)は %s 形式でも先に行われるので、重い計算は公式ドキュメントにあるように if logger.isEnabledFor(logging.DEBUG): で囲みます。
同じログが 2 回、3 回と出る
logging.getLogger(“myapp”) でロガーを取り出して addHandler する関数を 3 回呼んだところ、1 回目のログは 1 行、2 回目は 2 行、3 回目は 3 行と、同じ行が重なって出ました。getLogger は同じ名前なら同じロガーを返すので、addHandler するたびにハンドラーが積み重なるためです。ハンドラーの設定はプログラムの起動時に 1 回だけ行います。また、自分でハンドラーを付けたロガーがあるのに basicConfig でルートロガーにもハンドラーを付けると、ログが親にも渡されて 2 回出ます。
よくある質問
Linux のサーバーでバックグラウンド実行したときのログは?
nohup などで動かすと、画面(標準出力・標準エラー出力)への出力はファイルに回すことになります。その方法は「Linuxのプロセス管理」の nohup の節で説明しています。logging で FileHandler や RotatingFileHandler を使ってファイルに書いておけば、起動方法に関係なく決まった場所にログが残り、ファイルが大きくなりすぎる心配もありません。
まとめ
- 利用者に見せる結果は print、後で調べるための記録は logging
- 何も設定しないと WARNING 以上しか出ない。basicConfig の level で変える
- basicConfig はメインのファイルの最初で 1 回だけ。ファイルに書くなら encoding=”utf-8″
- 各ファイルで
logger = logging.getLogger(__name__)を作って使う - 出力先ごとに設定を変えるなら Handler と Formatter、長く動かすなら RotatingFileHandler
- except の中では logger.exception でトレースバックを残す。パスワードや個人情報はログに出さない
関連する記事・ツール
- Pythonの例外処理入門|try・except・finally・raiseの使い方とトレースバックの読み方
- Pythonのファイル読み書き|open・with・encoding指定と文字化けの直し方
- Pythonのdatetimeの使い方|日時の計算・タイムゾーン・Unix時間を実例で解説
- Linuxのプロセス管理|ps・top・killの使い方とバックグラウンド実行
- Pythonのf文字列(f-string)の使い方|書式指定・桁区切り・ゼロ埋めを実例で解説
- .envと環境変数で秘密情報を守る|APIキーをGitに上げない方法と漏れたときの対処
- 標準出力・標準エラーとリダイレクト|2>&1・tee・/dev/nullの使い方
- Pythonのデバッガーpdbの使い方|breakpoint()で止めて変数を調べる