Pythonのargparseの使い方|コマンドライン引数の受け取り方を実例で解説
Python のスクリプトに「どのファイルを処理するか」などを実行時に指定したいとき、標準ライブラリの argparse を使うと、py count.py data.txt --skip-blank のようなコマンドを数十行で作れます。ヘルプやエラー表示も自動で用意されます。
この記事では、ファイルの行数を数える小さな CLI ツール(コマンドラインで使うツール)を作りながら、sys.argv との違いから相互排他グループ・サブコマンドまでを順に説明します。出力は Windows 11 の PowerShell 5.1 と Git Bash で、Python 3.12.6 を使って実際に実行したものです(ヘルプの文面もそのまま載せています)。仕様は公式ドキュメントの argparse チュートリアルとリファレンス(英語原文)で確認しました。
argparse とは?sys.argv との違い
コマンドで py スクリプト名 の後ろに書いた文字はコマンドライン引数と呼ばれ、Python では sys.argv というリストで受け取れます。公式ドキュメントでは「Python スクリプトに渡されたコマンドライン引数のリスト。argv[0] はスクリプト名」と説明されています。まず中身を見てみます。次のコードを argv_test.py として保存します。
import sys
print(sys.argv)
PowerShell で、保存したフォルダーに移動してから実行します。
py argv_test.py *.md -n 5 "my memo.txt"
['argv_test.py', '*.md', '-n', '5', 'my memo.txt']
空白で区切られた文字が、そのまま文字列のリストになっています。5 も文字列の '5' で、-n と 5 がセットだという情報もありません。
同じコマンドを Git Bash で実行すると、結果が変わります。
py argv_test.py *.md -n 5 "my memo.txt"
['argv_test.py', 'memo.md', '-n', '5', 'my memo.txt']
Git Bash(bash)は *.md を、そのフォルダーにある memo.md に展開してから Python に渡します。PowerShell では展開されず、*.md のまま届きます。
sys.argv だけで処理すると、必須チェック・数値への変換・ヘルプなどを全部自分で書くことになります。path = sys.argv[1] だけのスクリプトを引数なしで実行すると、IndexError: list index out of range のトレースバックが出るだけで、何を指定すればよいのか分かりません。
| sys.argv | argparse | |
|---|---|---|
| 受け取る形 | 文字列のリスト | 名前で取り出せるオブジェクト(args.file など) |
| 数値などへの変換 | 自分で int() する | type=int で自動 |
| 必須チェック・入力ミス | 自分で書く | usage とエラーを表示して終了(終了コード 2) |
| ヘルプ(-h) | 自分で書く | 自動で作られる |
いちばん小さな形:位置引数を 1 つ受け取る
argparse の基本は、ArgumentParser を作る → add_argument で受け取る引数を登録する → parse_args で解析する、の 3 ステップです。ファイル名を 1 つ受け取って行数を表示するスクリプトを step1.py として保存します(ファイルの読み方は「Pythonのファイル読み書き」を参照)。
import argparse
parser = argparse.ArgumentParser(description="テキストファイルの行数を数えます。")
parser.add_argument("file", help="行数を数えるファイル")
args = parser.parse_args()
with open(args.file, encoding="utf-8") as f:
print(sum(1 for _ in f))
"file" のようにハイフンで始まらない名前で登録した引数は位置引数になります。公式チュートリアルによれば「書かれた位置」で意味が決まる引数で、省略できません。値は args.file で取り出します。5 行のファイル hello.py を渡すと(py step1.py hello.py)、5 と表示されました。
-h(または --help)を付けると、自分では何も書いていないのにヘルプが表示されます。
py step1.py -h
usage: step1.py [-h] file
テキストファイルの行数を数えます。
positional arguments:
file 行数を数えるファイル
options:
-h, --help show this help message and exit
1 行目の usage は使い方の要約で、[ ] で囲まれたものは省略できる引数です。description と help に渡した文が説明として表示されます。「options:」などは Python が出す英語の固定の文です(3.10 より前は「optional arguments:」)。ヘルプを出すとそこで終了します。
ファイル名を付け忘れると、usage とエラーが表示されて終了します。
py step1.py
usage: step1.py [-h] file
step1.py: error: the following arguments are required: file
ファイル名を 2 つ渡すと error: unrecognized arguments: notes.txt(知らない引数がある)になります。
オプション引数を追加する(default と action=”store_true”)
-e や --skip-blank のようにハイフンで始まる名前で登録した引数はオプション引数になり、省略できます。短い名前(-e)と長い名前(--encoding)を両方登録できます。step2.py では、解析結果をそのまま print して中身を確かめます。
import argparse
parser = argparse.ArgumentParser(description="テキストファイルの行数を数えます。")
parser.add_argument("file", help="行数を数えるファイル")
parser.add_argument("-e", "--encoding", default="utf-8",
help="文字コード(既定: %(default)s)")
parser.add_argument("--skip-blank", action="store_true", help="空行を数えない")
args = parser.parse_args()
print(args)
help の中の %(default)s は、ヘルプを表示するときに default の値に置き換わります。オプションを付けて実行すると、こうなります。
py step2.py hello.py --skip-blank -e cp932
Namespace(file='hello.py', encoding='cp932', skip_blank=True)
ここから次のことが分かります。
- 省略したオプションには default の値が入る(default を書かないと None)
action="store_true"は値を取らない「スイッチ」。付ければ True、付けなければ False になる- 属性名は最初の長い名前から決まり、途中の
-は_に変わる(--skip-blank→args.skip_blank) - オプションは位置引数の前にも後ろにも書ける
値は --encoding=shift_jis のように = でもつなげます。長い名前は紛れがなければ省略でき、--skip でも --skip-blank と見なされました(allow_abbrev=False で無効にできます)。つづりを間違えた --skp は error: unrecognized arguments: --skp になります。
add_argument のよく使う引数
type と choices:値のチェックを任せる
type=int を付けると int() で変換した値が入り、変換できない値はエラーになります。choices は一覧にない値をはじきます。後で作る完成版(linecount.py)での実行結果です。
py linecount.py notes.txt --min abc
usage: linecount.py [-h] [-e ENCODING] [--skip-blank] [--min N] [--ext EXT]
[--format {text,csv}] [-v | -q]
files [files ...]
linecount.py: error: argument --min: invalid int value: 'abc'
--format json なら、usage の後に error: argument --format: invalid choice: 'json' (choose from 'text', 'csv') と表示されます。
type には自作の関数も渡せます。公式リファレンスによると、その関数が ArgumentTypeError・TypeError・ValueError を送出すると、argparse が受け止めて見やすいエラーメッセージにします(例外については「Pythonの例外処理入門」を参照)。
action:store_true・count・append
| action | 動き | 省略したときの値 |
|---|---|---|
| “store”(既定) | 値を 1 つ受け取って入れる | default(なければ None) |
| “store_true” | 付けると True | False |
| “count” | 付けた回数を数える(-vv なら 2) | None(default=0 を付ける) |
| “append” | 何度も指定でき、値をリストにためる | None |
count は「-v で少し詳しく、-vv でもっと詳しく」のような指定に、append は --ext .py --ext .md(結果は ['.py', '.md'])のような繰り返しに使います。
nargs:1 つの引数で受け取る値の数
| nargs | 意味 |
|---|---|
| 省略 | 値を 1 つ(リストにならない) |
| 整数 N | ちょうど N 個をリストで |
| “?” | 0 個か 1 個。なければ default |
| “*” | 0 個以上をリストで |
| “+” | 1 個以上をリストで(0 個はエラー) |
たとえば parser.add_argument("--size", nargs=2, type=int, metavar=("W", "H")) に --size 1280 720 を渡すと args.size は [1280, 720] になり、--size 1280 だけだと error: argument --size: expected 2 arguments になりました。nargs="?" と default を組み合わせると、「省略できる位置引数」も作れます。
required:オプション引数を必須にする
add_argument("--user", required=True) とすると、–user がないとき error: the following arguments are required: --user になります。ただし公式リファレンスは「利用者はオプションを省略できるものと考えるので、必須のオプションはできるだけ避けるべき」としています。まず位置引数にできないか考えましょう。
完成版:ファイルの行数を数える CLI を作る
ここまでの機能をまとめて、linecount.py を作ります。複数のファイルを受け取り(nargs=”+”)、文字コードの指定、空行を除く、N 行以上だけ表示、拡張子で絞り込み、CSV 形式での出力、詳しい表示(-v)と合計だけの表示(-q)ができます。
import argparse
import glob
import sys
from pathlib import Path
def count_lines(path, encoding, skip_blank):
with open(path, encoding=encoding) as f:
if skip_blank:
return sum(1 for line in f if line.strip())
return sum(1 for _ in f)
def main():
parser = argparse.ArgumentParser(
description="テキストファイルの行数を数えます。")
parser.add_argument("files", nargs="+", help="行数を数えるファイル(複数可)")
parser.add_argument("-e", "--encoding", default="utf-8",
help="文字コード(既定: %(default)s)")
parser.add_argument("--skip-blank", action="store_true",
help="空行を数えない")
parser.add_argument("--min", type=int, default=0, metavar="N",
help="N 行以上のファイルだけ表示する")
parser.add_argument("--ext", action="append",
help="対象にする拡張子(例: .py)。何度でも指定できる")
parser.add_argument("--format", choices=["text", "csv"], default="text",
help="出力形式(既定: %(default)s)")
group = parser.add_mutually_exclusive_group()
group.add_argument("-v", "--verbose", action="count", default=0,
help="詳しく表示する(-vv でさらに詳しく)")
group.add_argument("-q", "--quiet", action="store_true",
help="合計だけを表示する")
args = parser.parse_args()
if args.verbose >= 2:
print(args, file=sys.stderr)
names = []
for pattern in args.files:
# PowerShell は *.txt を展開しないので、ここで展開する
names.extend(glob.glob(pattern) or [pattern])
total = 0
for name in names:
if args.ext and Path(name).suffix not in args.ext:
if args.verbose:
print(f"スキップ: {name}", file=sys.stderr)
continue
try:
n = count_lines(name, args.encoding, args.skip_blank)
except OSError as e:
parser.error(f"{name} を開けません({e.strerror})")
except UnicodeDecodeError:
parser.error(f"{name} を {args.encoding} として読めません。-e で文字コードを指定してください")
total += n
if n < args.min or args.quiet:
continue
if args.format == "csv":
print(f"{name},{n}")
else:
print(f"{n:>6} {name}")
if args.format == "csv":
print(f"合計,{total}")
else:
print(f"{total:>6} 合計")
if __name__ == "__main__":
main()
ポイントは次のとおりです。
- ファイルが開けない・読めないときは
parser.error()を呼ぶ。usage とメッセージを標準エラー出力に出し、終了コード 2 で終わる glob.globで*.txtのようなパターンを展開している。PowerShell からも Git Bash と同じように使うため- スキップなどのメッセージは標準エラー出力へ出し、結果と混ざらないようにしている
f"{n:>6} {name}"は行数を 6 桁の右寄せで表示する書式(「Pythonのf文字列の使い方」を参照)
Shift_JIS のファイルを既定の UTF-8 で読むと error: sjis.txt を utf-8 として読めません。-e で文字コードを指定してください で止まり、-e cp932 を付けると数えられました(「文字コードとは?」も参照)。
ヘルプは次のとおりです(行の折り返し位置は、ウィンドウの幅によって変わります。ここでは幅 80 文字のときのものです)。
py linecount.py -h
usage: linecount.py [-h] [-e ENCODING] [--skip-blank] [--min N] [--ext EXT]
[--format {text,csv}] [-v | -q]
files [files ...]
テキストファイルの行数を数えます。
positional arguments:
files 行数を数えるファイル(複数可)
options:
-h, --help show this help message and exit
-e ENCODING, --encoding ENCODING
文字コード(既定: utf-8)
--skip-blank 空行を数えない
--min N N 行以上のファイルだけ表示する
--ext EXT 対象にする拡張子(例: .py)。何度でも指定できる
--format {text,csv} 出力形式(既定: text)
-v, --verbose 詳しく表示する(-vv でさらに詳しく)
-q, --quiet 合計だけを表示する
フォルダーには linecount.py・ftool.py・hello.py(5 行)・notes.txt(10 行)・memo.md(3 行、うち空行 1)を置いて実行しました。
py linecount.py hello.py notes.txt memo.md
5 hello.py
10 notes.txt
3 memo.md
18 合計
–ext(append)と -v(count)を組み合わせると、対象外のファイルも分かります。
py linecount.py *.py *.md --ext .md -v
スキップ: ftool.py
スキップ: hello.py
スキップ: linecount.py
3 memo.md
3 合計
Git Bash で、CSV 形式・5 行以上のファイルだけを出します。
py linecount.py notes.txt hello.py --min 5 --format csv
notes.txt,10
hello.py,5
合計,15
相互排他グループ:同時に指定できないオプション
「詳しく表示」と「合計だけ表示」は矛盾します。add_mutually_exclusive_group() で作ったグループに登録したオプションは、1 つしか指定できなくなります。両方付けると、usage(ここでは省略)の後に次のエラーが出ます。
py linecount.py hello.py -v -q
linecount.py: error: argument -q/--quiet: not allowed with argument -v/--verbose
add_mutually_exclusive_group(required=True) にすると、「どれか 1 つは必ず指定する」という意味になります。
サブコマンド:git commit のように機能を分ける
git commit や pip install のように、最初の単語で機能を切り替える形をサブコマンドと呼びます。argparse では add_subparsers() で作ります。行数を数える lines と、先頭の行を表示する head を持つ ftool.py の例です。
import argparse
def cmd_lines(args):
with open(args.file, encoding="utf-8") as f:
print(sum(1 for _ in f))
def cmd_head(args):
with open(args.file, encoding="utf-8") as f:
for i, line in enumerate(f):
if i >= args.n:
break
print(line, end="")
def main():
parser = argparse.ArgumentParser(description="テキストファイルの小さな道具箱")
sub = parser.add_subparsers(dest="command", required=True,
help="使うコマンド")
p_lines = sub.add_parser("lines", help="行数を数える")
p_lines.add_argument("file")
p_lines.set_defaults(func=cmd_lines)
p_head = sub.add_parser("head", help="先頭の行を表示する")
p_head.add_argument("file")
p_head.add_argument("-n", type=int, default=5, help="表示する行数(既定: %(default)s)")
p_head.set_defaults(func=cmd_head)
args = parser.parse_args()
args.func(args)
if __name__ == "__main__":
main()
sub.add_parser() が返すパーサーには、普通どおり add_argument できます。公式リファレンスで「特に効果的な方法」として紹介されているとおり、set_defaults(func=関数) で「このサブコマンドならこの関数」と結び付け、最後に args.func(args) で呼び出します。dest="command" を付けると、どのサブコマンドが選ばれたかが args.command に入り、required=True でサブコマンドの指定を必須にできます。
py ftool.py -h
usage: ftool.py [-h] {lines,head} ...
テキストファイルの小さな道具箱
positional arguments:
{lines,head} 使うコマンド
lines 行数を数える
head 先頭の行を表示する
options:
-h, --help show this help message and exit
py ftool.py head notes.txt -n 3 なら先頭 3 行(1・2・3)が表示されました。サブコマンドごとのヘルプは、py ftool.py head -h のようにサブコマンドの後ろに -h を付けます。
存在しないサブコマンドを指定すると、選べるものが表示されます。なお、head 用の -n を py ftool.py -n 3 head notes.txt のように前に書くと、invalid choice: '3' という分かりにくいエラーになりました。サブコマンド用のオプションはサブコマンドの後ろに書きます。
py ftool.py tail notes.txt
usage: ftool.py [-h] {lines,head} ...
ftool.py: error: argument command: invalid choice: 'tail' (choose from 'lines', 'head')
エラー時の表示と終了コード 2
argparse は引数がおかしいと usage と「プログラム名: error: メッセージ」を標準エラー出力に出し、終了コード 2 で終わります(公式リファレンスの error() の項)。-h のときは 0 です。PowerShell では $LASTEXITCODE、Git Bash では $? で確かめられます。
py linecount.py notes.txt --min abc; $LASTEXITCODE
usage とエラーの後に 2 と表示されました。Git Bash でも同じく 2 です。
py linecount.py notes.txt --min abc; echo $?
トレースバックで終わったとき(sys.argv[1] の IndexError の例)は 1 でした。シェルスクリプトなどから呼ぶときは、0 なら成功、2 なら引数の誤り、と区別できます。
よくある間違い
type=bool で True/False を受け取ろうとする
parser.add_argument("--debug", type=bool) と書いて --debug False を渡すと、結果は True になります。--debug 0 も True で、False になるのは空文字 --debug "" のときだけでした。bool() は空でない文字列をすべて True にするためで、公式リファレンスもすすめていません。オン・オフは action="store_true" で表しましょう(Python 3.9 以降なら action=argparse.BooleanOptionalAction で --debug と --no-debug を両方作れます)。
count に default=0 を付け忘れる
action="count" だけだと、-v を付けなかったときの値は 0 ではなく None です。if args.verbose >= 1: と比べると TypeError: '>=' not supported between instances of 'NoneType' and 'int' で止まりました。default=0 を付けましょう。
PowerShell で *.txt がファイル名として届く
PowerShell は *.txt を展開しません。glob の処理を入れる前の linecount.py で py linecount.py *.txt を実行すると、OSError: [Errno 22] Invalid argument: '*.txt' のトレースバックになりました。完成版のように glob.glob で展開するか、PowerShell 側で py linecount.py (Get-ChildItem *.txt).Name のようにファイル名を渡します。
まとめ
- ArgumentParser → add_argument → parse_args の 3 ステップで使う。-h のヘルプは自動で作られる
- ハイフンなしの名前は位置引数(必須)、ハイフン付きはオプション引数(省略可)
- type・choices で値のチェックを任せ、スイッチは action=”store_true”、回数は count(default=0)、繰り返しは append
- 引数の誤りは usage とエラーを表示して終了コード 2。自分のチェックも parser.error() でそろえる
- 同時に使えないオプションは相互排他グループ、機能を分けるならサブコマンド
関連する記事・ツール
- Pythonのファイル読み書き|open・with・encoding指定と文字化けの直し方
- Pythonの例外処理入門|try・except・finally・raiseの使い方
- Pythonのloggingの使い方|printから卒業するログ出力の基本と設定例
- 環境変数PATHとは?Windows・Linuxの確認・設定と「認識されません」の直し方
- Pythonのf文字列(f-string)の使い方|書式指定・桁区切り・ゼロ埋めを実例で解説
- Pythonのpathlibの使い方|Pathでファイル・フォルダーを操作する方法と注意点