Python WebAcademy

Python WebAcademy Blog

Typer 0.29がリリース。コマンドラインの引数のチェックにPydanticを使うようになり、日時の受け付け方やエラーの文面が変わったニュースを初心者向けに解説

|

2026年11月9日、Pythonでコマンドラインのツールを作れるライブラリTyperの0.29.0が公開されました。引数のチェックに、内部でPydanticを使うようになっています。タイムゾーン付きの日時を受け付けるようになった一方で、click_typeの削除など、注意したい変更もあります。0.28.0と0.29.1で同じコードを動かした結果とともに整理します。

2026年11月9日、Pythonでコマンドラインのツールを作れるライブラリTyperの0.29.0が公開されました。コマンドに渡された引数のチェックに、内部でPydanticを使うようになったのが大きな変更です。

続く11月11日の0.29.1では、Python 3.15への対応も加わりました。その少し前、11月6日には0.28.0も出ています。

Typerは、FastAPIと同じ作者が手がけるライブラリです。今回は、0.28.0と0.29.1で同じコードを動かしながら、何が変わったのかを見ていきます。

まずはTyperとはどんなものか

最初に、Typerを知らない方のために、どんなライブラリなのかを簡単に紹介します。Typerは、関数の引数に型ヒントを書くだけで、コマンドラインのツールを作れるライブラリです。

コマンドラインのツールとは、ターミナルでpython app.py taro --count 2のように、文字を打って動かすプログラムのことです。打ち込んだ文字を、プログラムの中で使える値に変えてくれます。

最小のツールを作ってみた

実際に、名前と回数を受け取って、あいさつを表示するツールを作ってみました。あとで日時の話もするので、予定の日時を受け取るwhenも入れています。

from datetime import datetime

import typer

app = typer.Typer()


@app.command()
def main(name: str, count: int = 1, when: datetime | None = None):
    for _ in range(count):
        print(f"こんにちは、{name}さん")
    if when:
        print("予定:", repr(when))


if __name__ == "__main__":
    app()

python app.py taro --count 2と打つと、こんにちは、taroさん、が2回表示されました。既定値のある引数は、--countのようなオプションになります。

型ヒントを書くだけで、文字を数に変えてくれるのがTyperの手軽なところです。型ヒントの基本は、こちらで紹介しています。【関連記事】Pythonの型ヒントとは?

標準ライブラリのargparseとの違い

Pythonには、コマンドラインの引数を扱う標準ライブラリのargparseもあります。大まかに比べると、次のような違いがあります。

項目 argparse Typer
引数の決め方 add_argument()で1つずつ登録する 関数の引数と型ヒントで決まる
ヘルプの表示 自動で作られる 色付きの枠で、自動で作られる
追加で入れるか 標準ライブラリ pipで入れるライブラリ

argparseの使い方は、こちらで紹介しています。【関連記事】argparseでコマンドラインツールを作る

0.28から0.29で何が変わったのかを整理しよう

続いて、今回の範囲の主な変更を表にまとめます。内容は、Typerの公式リポジトリにあるリリースノートにもとづいています。

版 公開日 主な変更
0.28.0 11月6日 metavarを設定すると、既定のオプション名が変わってしまう問題を修正
0.29.0 11月9日 引数のチェックに、内部でPydanticを使うように
0.29.1 11月11日 Python 3.15と、GILのない3.15tに対応

0.29.0のリリースノートには、互換性に関わる変更として5つの項目が並んでいます。PyPIの記録によると、0.29.1が必要とするPythonは3.10以上です。

引数のチェックにPydanticを使うように

まずは、今回の中心となる変更から見ていきましょう。Pydanticとは、型ヒントをもとに、データが正しい形かどうかを確かめるライブラリです。

リリースノートによると、Typerは0.29.0から、内部でPydanticを使って引数をチェックするようになりました。これまでの書き方をなるべくそのまま使えるよう、少しずつ移していく方針だと説明されています。

Pydanticが必ず入るように

その結果、Pydanticの2.5.3以上が、必ず一緒に入る依存ライブラリになりました。実際に、新しい仮想環境に入れたときの、Typerが必要とするライブラリを比べてみます。

版 pip showで表示された依存ライブラリ
0.28.0 annotated-doc、rich、shellingham
0.29.1 annotated-doc、pydantic、rich、shellingham

0.29.1では、Pydanticの2.14.3が一緒に入りました。仮想環境のライブラリの置き場所も、手元では44MBから54MBに増えています。

Pydanticの基本は、こちらで紹介しています。【関連記事】Pydantic v2の使い方

エラーの文面が変わった

Pydanticを使うようになったことで、間違った値を渡したときのエラーの文面も変わりました。先ほどのツールに、--count abcと数ではない文字を渡してみます。

Typer 0.28.0
Invalid value for '--count': 'abc' is not a valid int.

Typer 0.29.1
Invalid value for '--count': Input should be a valid integer, unable to parse string as an integer

どちらの版でも、ツールは止まり、終了コードは2でした。ただ、0.29.1では、Pydanticらしい言い回しのエラーになっています。

エラーの文面を読み取って処理しているテストやスクリプトがある場合は、上げる前に確かめておきましょう。ヘルプの表示も、--whenの欄が日付の書式の一覧から<datetime>という短い表示に変わっていました。

日時の受け付け方が広がった

続いて、使う人にとって嬉しい変更です。リリースノートによると、日時の読み取りはPydanticのルールに従うようになり、Unixの時刻やタイムゾーン、秒の小数を受け付けるようになりました。

0.28.0と0.29.1で試してみた

実際に、先ほどのツールの--whenに、3つの形の日時を渡してみました。手元のPython 3.11で、それぞれの版を新しい仮想環境に入れた結果です。

--whenに渡した値 0.28.0 0.29.1
2026-11-17T12:00:00+09:00 書式が合わずエラー 日本時間の12時として受け付けた
1700000000 書式が合わずエラー 2023年11月14日22時13分20秒、世界の基準の時刻
2026-11-17T12:00:00.5 書式が合わずエラー 0.5秒まで含めて受け付けた

0.28.0では、決められた3つの書式のどれにも合わないとして、エラーになりました。0.29.1では、タイムゾーン付きの日時を、そのまま渡せるようになっています。

Unixの時刻とは、1970年1月1日からの秒数で日時を表す方法です。ログやAPIでよく見かける形なので、コピーしてそのまま渡せるのは便利ですね。

日時とタイムゾーンの扱いは、こちらで紹介しています。【関連記事】Pythonのdatetimeとは?

気をつけたい互換性の変更

ここからは、上げる前に気をつけたい変更です。リリースノートの互換性の項目から、初心者にも関係しそうなものを2つ試しました。

タプルの既定値が厳しくなった

1つ目は、複数の値をまとめて受け取るタプルの既定値です。これまでのTyperの説明では、次のように、Noneを並べた既定値を使う例が載っていました。

@app.command()
def main(user: tuple[str, int, bool] = (None, None, None)):
    print("user:", user)

何も渡さずに動かすと、0.28.0ではuser: (None, None, None)と表示されました。0.29.1では、None is not a valid stringというエラーで止まっています。

リリースノートでは、tuple[str, int, bool] | Noneと書いて既定値をNoneにし、Noneかどうかを確かめてから取り出す書き方が勧められています。実際にその形に直すと、0.28.0でも0.29.1でも同じように動きました。

@app.command()
def main(user: tuple[str, int, bool] | None = None):
    if user is None:
        print("userは指定されませんでした")
        return
    name, age, admin = user
    print(name, age, admin)

--user taro 30 yesと渡すと、どちらの版でもtaro 30 Trueと表示されました。リリースノートでも、こちらのほうが正しい書き方なので、不具合の修正と考えてもよいと書かれています。

click_typeが使えなくなった

2つ目は、型を自分で決めるためのclick_typeです。手元でtyper.Option(1, click_type=None)を試すと、0.28.0では受け付けられ、0.29.1では次のエラーになりました。

TypeError: Option() got an unexpected keyword argument 'click_type'

リリースノートによると、自分で型を決める新しい方法は、今後Pydanticを使って用意される予定です。まだ提供はされていないので、click_typeを使っている方は、上げるのを少し待つのも1つの手です。

なお、Typerは5月の0.26.0で、土台のClickというライブラリを、自分の中に取り込む形に変えています。そのため、今回の2つの版のどちらでも、Clickは別のライブラリとしては入っていませんでした。

そのほかの変更

リリースノートには、ほかにもいくつかの変更が並んでいます。代表的なものを表にまとめます。

版 中身
0.28.0 metavarを設定すると、既定のオプション名が変わってしまう問題を修正
0.29.0 Pydanticのエラーの文面に含まれる、端末の制御文字を無害にする
0.29.0 引数の処理の中で使う一部の属性を、コールバックから使えなくした
0.29.1 Python 3.15と3.15tへの対応

metavarとは、ヘルプの中で、値の場所に表示する名前のことです。3つ目は、引数を受け取ったときに呼ばれる関数の中で、Click由来の細かな属性を使っていた人に関係します。

上げる前にやっておきたいこと

最後に、Typerを0.29へ上げる前に確かめておきたいことを整理します。

順番 確認すること
1 Pydanticが一緒に入っても、ほかのライブラリとぶつからないか
2 エラーの文面を読み取るテストやスクリプトがないか
3 タプルの既定値に、Noneを並べたものを使っていないか
4 click_typeを使っていないか

私は10年ほどエンジニアとして開発に関わってきましたが、社内向けの小さなコマンドラインのツールを、何本もTyperで作ってきました。日時を受け取るツールでは、タイムゾーン付きの値をエラーにされ、毎回書き直して渡していたので、今回の変更はとても助かります。

まとめ

2026年11月9日、Typer 0.29.0が公開され、引数のチェックに内部でPydanticを使うようになりました。タイムゾーン付きの日時やUnixの時刻を受け付けるようになった一方で、エラーの文面が変わり、click_typeは使えなくなっています。

11月11日の0.29.1では、Python 3.15にも対応しました。コマンドラインのツールをTyperで作っている方は、上の確認ポイントを一度見直してみてください。

ここまでお読みいただきありがとうございました。

参考情報

次のアクション

記事で学んだ内容を実際に動かしてみよう

Python WebAcademyでは、ブラウザ上でコードを書きながら基礎から実践まで体系的に学べます。

Python WebAcademyの学習画面

あわせて読む

関連記事

ブログ一覧へ

Python学習ロードマップ

まずはこの3講座から

記事で気になったテーマを、順番に手を動かしながら学べます。

ロードマップを見る