Python 3.14でargparseの候補が出ないとき｜suggest_on_errorの対象と設定

結論：Python 3.14では有効化と対象の確認が必要

Python 3.14のargparseで入力ミスの候補を出すには、ArgumentParserへsuggest_on_error=Trueを設定します。ただし、候補表示の主な対象は文字列のchoicesに渡した値とサブパーサー名です。--mdoeのようなオプション名の打ち間違い全般を直す機能ではありません。

また、候補はエラーメッセージへ追加されるだけです。入力を自動修正して処理を続けることはなく、近い候補が見つからなければ提案は表示されません。

1．実行中のPythonの版を確認する

最初に、実際にCLIを動かしているPythonのメジャー版とマイナー版を確認します。

python -c "import sys; print(sys.version_info[:2])"

Python 3.14系なら、表示例は次の形です。

(3, 14)

suggest_on_errorはPython 3.14で追加されました。3.14では既定値がFalseなので、使いたい場合は明示的な有効化が必要です。バージョン指定のないPythonドキュメントは3.15を示すことがあり、3.15では既定値がTrueに変わっています。3.14の挙動を確認するときは、Python 3.14のargparse公式ドキュメントを参照してください。

2．suggest_on_errorを有効にする

Python 3.14だけを対象にするコードなら、コンストラクターで有効化できます。

import argparse

parser = argparse.ArgumentParser(
    suggest_on_error=True,
)

以下の再現例では、エラー出力を比較しやすくするためcolor=Falseも指定します。これはPython 3.14で追加された別機能であり、候補表示の有無には関係しません。色出力の扱いはPython 3.14のargparseで色を無効にする方法で分けて確認できます。

3．文字列choicesの打ち間違いを試す

まずは、文字列だけで構成したchoicesの最小例です。次の内容をchoices_demo.pyとして保存します。

import argparse

parser = argparse.ArgumentParser(
    prog="tool.py",
    suggest_on_error=True,
    color=False,
)
parser.add_argument("--mode", choices=["debug", "dryrun"])
parser.parse_args()

debugをdebuggと打ち間違えた例です。

python choices_demo.py --mode debugg

公式仕様に沿う出力例は次のとおりです。

usage: tool.py [-h] [--mode {debug,dryrun}]
tool.py: error: argument --mode: invalid choice: 'debugg', maybe you meant 'debug'? (choose from 'debug', 'dryrun')

maybe you meant 'debug'?が候補部分です。候補が出ても解析はエラーで終了し、debugへ置き換えて実行されるわけではありません。

4．サブコマンド名の打ち間違いを試す

サブパーサーで定義したコマンド名も対象です。次の内容をsubcommands_demo.pyとして保存します。

import argparse

parser = argparse.ArgumentParser(
    prog="project.py",
    suggest_on_error=True,
    color=False,
)
commands = parser.add_subparsers(required=True)
commands.add_parser("deploy")
commands.add_parser("delete")
parser.parse_args()

deployをdeplyと入力します。

python subcommands_demo.py deply

出力例では、近いサブコマンド名が示されます。

usage: project.py [-h] {deploy,delete} ...
project.py: error: argument {deploy,delete}: invalid choice: 'deply', maybe you meant 'deploy'? (choose from 'deploy', 'delete')

5．候補が出ない入力を区別する

suggest_on_error=Trueでも、すべての入力エラーに候補が付くわけではありません。

同じchoices_demo.pyでオプション名を間違えると、候補ではなく未認識の引数として扱われます。

python choices_demo.py --mdoe debug

usage: tool.py [-h] [--mode {debug,dryrun}]
tool.py: error: unrecognized arguments: --mdoe debug

この結果は設定漏れではありません。--modeの値を間違えたのか、--mode自体を間違えたのかを分けて確認するのが要点です。

3.13以前も動かすコードでは属性として設定する

Python 3.13以前へsuggest_on_error=Trueをコンストラクター引数として無条件に渡すと、未知のキーワード引数による互換性問題が起きます。公式ドキュメントは、パーサーを作成したあとで属性を設定する書き方を紹介しています。

import argparse

parser = argparse.ArgumentParser()
parser.suggest_on_error = True

この形なら、Python 3.14では候補機能を有効にできます。一方、3.13以前のargparseへ機能そのものが追加されるわけではないため、属性を設定しても候補表示は働きません。古い版にも同じ候補動作が必要なら、Pythonの対応版を上げるか、独自のエラー処理を用意する必要があります。

よくある質問

suggest_on_errorをTrueにしたのに、なぜ候補が出ませんか？

まずPython 3.14で動いているかを確認し、次に誤入力が文字列choicesの値またはサブパーサー名かを確認します。オプション名と整数choicesは対象外で、候補から遠い文字列も提案が出ないことがあります。

候補が出たら、自動的に正しい値で実行されますか？

実行されません。候補はエラーメッセージの補助情報です。利用者が正しい値を入力し直す必要があります。

Python 3.13以前でも属性を設定すれば使えますか？

使えません。属性設定は新しいキーワード引数を古い版へ渡さないための互換的な書き方であり、3.13以前へ候補機能を移植するものではありません。

まとめ

Python 3.14で候補が出ないときは、実行版が3.14か、suggest_on_error=Trueを有効にしたか、誤入力が文字列choicesまたはサブパーサー名か、の順に確認します。--flag名の打ち間違いまで直す機能だと考えず、対象外のエラーと切り分けると原因を早く特定できます。

関連記事

• Python 3.14のargparseで色コードを消す方法｜color=False・NO_COLOR・ログ保存
• uv python pinしたのにPythonが変わらない？PATHとuv runを切り分ける