サイトアイコン ITC Media

【初心者向け】Python argparseの使い方完全ガイド｜CLIツール作成を実例で解説

ITC運営

(最終更新月: 2025年07月18日)

✓当記事はこんな方におすすめです

「Pythonのargparseを使ったコマンドラインツールの作り方を知りたい」

「argparseで何ができるか、基本から活用テクまでやさしく学びたい」

「実際のコード例・現場での使い方を踏まえて理解したい」

✓当記事で理解できること

この記事では、Pythonの標準ライブラリであるargparseを使ったコマンドライン引数の処理について、初心者や未経験者に向けて基礎から応用まで徹底解説します。

実際に動くサンプルコードや、開発現場でありがちな失敗例・注意点も交えながら一つひとつ丁寧に解説しています。

最後まで読んでいただければ、Pythonで実践的なCLIツールが自信を持って作れるようになります。それでは、一緒に見ていきましょう。

運営者プロフィール

現在はIT企業のプロダクトマネージャーとして、個人向け/社内向けシステムなど、複数のシステム開発・運営に携わっています。

Webサイト構築やECサイトの開発経験に加えて、PythonなどのプログラミングやSalesforceなどのクラウドアプリケーションに関する幅広い知識・経験を活かして「プログラミング初心者がスムーズに学べるサイト」を目指しています。

Githubでは、趣味で作成したアプリなどを公開しています。

https://github.com/Yulikepython/

✔人に見せても恥ずかしくないコードを書こう

「リーダブルコード」は、わかりやすく良いコードの定義を教えてくれる本です。

  • 見るからにきれいなコードの書き方
  • コードの分割方法
  • 変数や関数の命名規則

エンジニアのスタンダートとすべき基準を一から解説しています。

何回も読むのに値する本なので、ぜひ手にとって読んでみてください。

リーダブルコード ―より良いコードを書くためのシンプルで実践的なテクニック
created by Rinker

argparseとは？PythonでCLIツールを作る理由

このセクションでは、そもそもargparseとは何か、その特徴とメリットを解説します。

なぜなら、Pythonで実用的なコマンドラインツールを開発したい方にとって、「なぜargparseを使うのか」をまず理解することが出発点になるからです。

argparseはどんなもの？

argparseは、Python標準の「コマンドライン引数パーサ」です。

このモジュールは、コマンドラインから渡された文字列を「分かりやすく」「安全に」受け取り、欲しい形で使えるようにしてくれます。

たとえばファイル名や実行オプションなどを簡単に受け取れるので、CLIツールの開発が圧倒的に効率的になります。

多くの現場のPythonスクリプトはargparseで柔軟にパラメータ管理をしています。

CLIツールがなぜ役立つのか

Python初心者は「なぜわざわざコマンドラインから値を渡すんだろう？」と疑問に思うかもしれません。

実際、実務では以下のような場面でCLIツールが活躍します。

argparseを活用できると「現場で役立つ自動ツール」がすぐ作れる、これが圧倒的メリットです。

他の方法やモジュールとの違い

Pythonでコマンドライン引数を扱うには、sys.argvやgetopt、最近ではサードパーティのclickやfireも人気です。

ですが、argparseは「公式・標準搭載」かつ「高機能」&「拡張性十分」なため、導入コストも低くオススメです。

より複雑なUIや対話型CLIが必要ならclickなどを検討できますが、学習段階・実務のほとんどの場面ではargparseで十分ニーズを満たせます。

詳しい比較や選び方については後半で取り上げます。

argparseの基本的な使い方と実例

このセクションでは、Pythonでargparseを使う基本手順と、最初に知っておきたい要点を実例つきで整理します。

なぜなら、「引数を受け付ける」仕組みは最初は難しそうに見えますが、実は手順さえ押さえれば短時間で現場投入できる便利さがあるからです。

最小構成のサンプルコード

argparseで最低限の引数処理を行うには、たった数行でOKです。

以下の基本形を覚えておくとあらゆる場面で役立ちます。

import argparse

parser = argparse.ArgumentParser()
parser.parse_args()

これだけで–helpや「エラー時のガイド」まで生成してくれるため、完成度が高いCLIの土台が即完成します。

本格的なツールではこの上に引数をどんどん足していきます。

位置引数・オプション引数の違い

argparseの引数には大きく2種類あります。

この違いをきちんと使い分けるとユーザーにとって扱いやすいツールが作れます。

例えば「ファイル名は必須」「モードは任意でデフォルト値あり」等、現場ニーズに合わせた設計が自在です。

コード例：名前・数値を受け取ってみる

具体的に、「名前」と「年齢」を受け取って表示する簡単なツールを作ってみます。

import argparse

parser = argparse.ArgumentParser(description="ユーザー情報を受け取るサンプル")
parser.add_argument("name", help="お名前を入力してください")
parser.add_argument("--age", type=int, default=20, help="年齢(整数)。未指定時は20")
args = parser.parse_args()

print(f"こんにちは、{args.name}さん！ 年齢: {args.age}")

この例では、「python script.py 山田 –age 22」のように実行できます。

helpオプションを自動生成してくれるので初心者ユーザーにもやさしいのがargparseの強みです。

よく使うargparseの便利機能まとめ

このセクションでは、よく使われる便利な実践テクや現場の引数設計に役立つ機能を解説します。

理由は、ちょっとした応用を知るだけで「現場で困らないCLIツール作成」ができるようになるからです。

オプション引数の短縮と型指定

便利な小技として覚えておきたいのが、「短縮指定」と「型変換」です。

たとえば-f, –fileの両方で入力できたり、int型やfloat型に自動変換できます。

parser.add_argument("-f", "--file", type=str, required=True, help="ファイルパス")
parser.add_argument("-n", "--num", type=int, default=10, help="数値(デフォルト10)")

この仕組みのおかげで、「ユーザーの入力ミスを未然に防ぐ」プログラムも簡単にできます。

短縮オプションは使いやすさ改善に不可欠な要素です。

デフォルト値や必須化の指定

必須引数はrequired=Trueで宣言。

デフォルト値が必要なときはdefault=値とします。

parser.add_argument("--mode", default="train", help="モード選択。未指定時は'train'")
parser.add_argument("--level", type=int, default=1, required=False)

未入力・未指定時の挙動も明示的に制御できるので、「想定外」が減ります。

業務ツールの品質向上にも役立つシンプルなテクニックです。

排他グループ・サブコマンド・ファイル読込

argparseには「排他グループ（片方だけしか指定できない）」「サブコマンド（gitのadd/commitのような）」を作る機能があります。

group = parser.add_mutually_exclusive_group()
group.add_argument('--train', action='store_true')
group.add_argument('--test', action='store_true')

また、サブコマンドはsubparsersを使うことで設計できます。

ファイルからまとめて設定値を読み込むこともできます（fromfile_prefix_charsなど）。

これら高機能オプションが「大規模CLI」や現場の自動化に一気に役立ちます。

argparseの現場活用・トラブルシューティング

このセクションでは、argparseを現場で使う上での注意点や、よくある落とし穴、トラブル時の解決法を具体例と共に紹介します。

なぜなら、CLIツールは開発時と運用時で遭遇する課題・エラーがけっこう多く、その対策を知っているだけで「失敗しないエンジニア」になれるからです。

エラー時の自動ヘルプ・メッセージ

argparseは「想定外の入力や型違い」に自動でエラーとヘルプ文を出してくれます。

うっかり実行時に”ValueError”などエラーが出ても利用者が困りません。

例えば実務では、int型を受け取る引数に文字列を誤入力した場合、下記のようにガイドが即表示されます。

# python myscript.py --age twenty
usage: myscript.py [-h] [--age AGE] name
myscript.py: error: argument --age: invalid int value: 'twenty'

初心者向けCLIや「初めて使う現場ツール」は、必ずargparseのヘルプを活用しましょう。

sys.argvだけでは物足りない理由

初心者が最初に触れるのはsys.argvリストかもしれません。

ですが、バリデーション（入力値の型検査や必須の管理）、ヘルプ生成、エラー対応などは手作業になりがちです。

現場では1人でも多くの人が触るCLIが増えるため、「ミスを事前に防ぐ」設計が重要になります。

argparseなら、こうした仕組みを一気に自動化してくれるので、初心者こそ積極活用がおすすめです。

サードパーティCLIライブラリとのすみ分け

よりリッチなCLI体験が欲しい場合、clickやfireなどの外部ライブラリも検討できます。

ですが、学習コスト・本番運用の信頼性・バージョン対応など総合的にみて、Python標準のargparseは「まず使いこなしたい必携ツール」です。

Python公式ドキュメントでも「ほとんどの場面でargparse推奨」と明記されています（参照: Python公式 ドキュメント）。

まとめ

本記事では、Pythonの標準ライブラリargparseについて、

を、実例・初心者向け目線で一通りご紹介しました。

argparseを正しく使いこなすことで、PythonのCLIツール開発が格段に効率化し、より多くの人が安心して利用できるツール設計が可能になります。

もしより高度な自動化やサーバ環境構築を目指す場合は、Docker×Pythonの環境構築方法もあわせてどうぞ。

更なるステップアップや本格的な現場経験を得たい方は、受講者満足度90%以上のプログラミングスクール【DMM WEBCAMP】
でプロに教わるのも選択肢です。

どんな小さな疑問や課題も、一歩ずつ解決してITエンジニアを目指しましょう。

モバイルバージョンを終了