【Python入門】argparseでコマンドライン引数を使ってみよう!

Pythonの標準モジュールであるargparseを使うと、コマンドラインで動くアプリケーションを作ることが出来ます。

コマンドラインでプログラムを実行させる時にコマンドに引数を渡すと、ヘルプメッセージなどのさまざまな情報を表示してくれます。

今回はコマンドライン引数を扱うときに使えるargparseの使い方について解説します。

  • 【基礎】argparseとは
  • 【実践】引数なしでargparseを使う方法
  • 【実践】引数ありでargparseを使う方法
  • 【おまけ】argparseを使わないで引数をパースする方法

argparseについて、初心者でもわかりやすく解説していますので、ぜひ参考にしてください!

本記事を読む前に、Pythonがどんなプログラミング言語なのかをおさらいしておきたい人は次の記事を参考にしてください。

→ Pythonとは?特徴やできること、活用例をわかりやすく簡単に解説

なお、その他のPythonの記事についてはこちらにまとめています。

目次

argparseとは

argparseとはPythonの標準ライブラリのひとつで、コマンドライン引数を扱いやすくしてくれるモジュールです。

コマンドライン引数とは、Pythonでプログラムを起動する際に指定する引数のことで、渡された引数はプログラム内で取得して使用することができます。

argparseはヘルプと使用方法のメッセージを作成し、引数の指定に誤りがあった場合にエラーを発生させます。argparseモジュールを使用することで簡潔にメッセージの作成と引数の解析を行うことができます。

argparseを使ってみよう!

引数なしでargparseを使う方法

まずはargparseを、コマンドの引数がない場合から確認していきましょう。

argparseモジュールのArgumentParserクラスのコンストラクタを使用してパーサーを生成します。

パーサーとは構文解析を行うプログラムや処理のことです。生成したパーサーからparse_argsメソッドを呼び出し実行すると、引数を解析しヘルプが表示できるようになります。

またArgumentParserクラスのコンストラクタの引数には以下のような設定ができるようになっています。

引数説明
progプログラム名を入力
usageプログラムの利用方法を記述
description引数の説明の前に表示される説明文
epilog引数の説明の後に表示される文字列
add_help[-h]/[–help]オプションの追加の有無

これらの使い方をサンプルコードを確認しながらみていきましょう。

まずはこちらのコードをご覧ください。

import argparse
 
# パーサーを作る
parser = argparse.ArgumentParser(
            prog='argparseTest.py', # プログラム名
            usage='Demonstration of argparser', # プログラムの利用方法
            description='description', # 引数のヘルプの前に表示
            epilog='end', # 引数のヘルプの後で表示
            add_help=True, # -h/–help オプションの追加
            )
 
# 引数を解析する
args = parser.parse_args()

こちらのコードを、argparseTest.pyという名前のファイルで実行しています。

コマンドラインでヘルプを表示させるためにこのようなコマンドを入力しました。

python argparseTest.py -h

実行結果

$ python argparseTest.py -h
usage: Demonstration of argparser
 
description
 
optional arguments:
  -h, --help            show this help message and exit
 
end

parserオブジェクトからparse_argsメソッドを呼び出し、引数の解析を実行しています。実行結果を確認すると、「usage」、「description」、「arguments(引数)」、「epilog」の順で表示されています。

引数ありでargparseを使う方法①

次にコマンドの引数がある場合について確認していきましょう。

引数を追加するためにArgumentParserクラスのadd_argumentメソッドを使用します。add_argumentメソッドはパーサーを生成した後で、parse_argsメソッドで引数の解析を行う前に指定します。add_argumentメソッドの引数にはこのような設定ができるようになっています。

まずは、

引数説明
name or flags位置引数もしくはオプション引数の指定
help引数の簡単な説明
action引数の取り扱いの指定
required引数の省略可否(オプション引数のみ)
type引数が変換される型

これらの指定について見ていきましょう。

name or flagsについて

引数が位置引数かオプション引数なのかを指定します。位置引数は関数に対して必須となる引数になります。

対して、オプション引数は与えても与えなくてもどちらでも良い引数になります。add_argumentメソッドの第1引数で指定します。

オプション引数には接頭辞「–」を付ける必要があり、実行時に引数を指定する場所はどこでも構いません。オプション引数以外の引数は位置引数として扱われ、実行時の引数の位置は決まっています。

それでは、サンプルコードで確認していきましょう。

import argparse
 
# パーサーを作る
parser = argparse.ArgumentParser(
            prog='argparseTest', # プログラム名
            usage='Demonstration of argparser', # プログラムの利用方法
            description='description', # 引数のヘルプの前に表示
            epilog='end', # 引数のヘルプの後で表示
            add_help=True, # -h/–help オプションの追加
            )
 
# 引数の追加
parser.add_argument('-v', '--verbose')
 
# 引数を解析する
args = parser.parse_args()

実行結果

$ python argparseTest.py -h
usage: Demonstration of argparser
 
description
 
optional arguments:
  -h, --help            show this help message and exit
  -v VERBOSE, --verbose VERBOSE
 
end

このサンプルコードでは、add_argumentメソッドの引数で接頭辞「-」がついたオプション引数を指定しています。接頭辞「–」で短い略語を指定し、接頭辞「—-」で長い名称を指定しています。

実行結果を確認すると、オプション引数(optional arguments):に「-v」、「–-verbose」と追加されているのがわかります。

しかし、「-h」、「–-help」の「show this help message and exit」のような記述が「-v」、「–-verbose」には見当たりません。

これは次の章のhelpで追加していきます。

helpについて

「-h」、「–-help」の「show this help message and exit」のような記述を「-v, –-verbose」にも追加します。

そのためにはhelpの項目を指定します。サンプルコードを確認してみましょう。

import argparse
 
# パーサーを作る
parser = argparse.ArgumentParser(
            prog='argparseTest', # プログラム名
            usage='Demonstration of argparser', # プログラムの利用方法
            description='description', # 引数のヘルプの前に表示
            epilog='end', # 引数のヘルプの後で表示
            add_help=True, # -h/–help オプションの追加
            )

# 引数の追加
parser.add_argument('-v', '--verbose', help='select mode')

# 引数を解析する
args = parser.parse_args()

実行結果

$ python argparseTest.py -h
usage: Demonstration of argparser
 
description
 
optional arguments:
  -h, --help            show this help message and exit
  -v VERBOSE, --verbose VERBOSE
                        select mode
 
end

このサンプルコードではadd_argumentメソッドのhelpの項目も指定しました。実行結果を確認すると「select mode」と表示されているのがわかります。

actionについて

actionの項目を指定して、引数の指定によって実行結果が変わることを確認していきます。

actionの項目にはこのような指定が出来ます。

引数説明
storeデフォルト
store_const定数を指定
stotre_true/store_falseTrue値もしくはFalse値を指定します。
appendリストに引数を追加
append_constリストに定数を追加
versionバージョン情報を表示

「store_const」や「append_const」で指定された定数はオプション引数がある場合は使用して、ない場合は使用しないなどの使い方をします。

それではサンプルコードを確認しましょう。

import argparse
 
# パーサーを作る
parser = argparse.ArgumentParser(
            prog='argparseTest', # プログラム名
            usage='Demonstration of argparser', # プログラムの利用方法
            description='description', # 引数のヘルプの前に表示
            epilog='end', # 引数のヘルプの後で表示
            add_help=True, # -h/–help オプションの追加
            )
 
# 引数の追加
parser.add_argument('-v', '--verbose', help='select mode',
                    action='store_true')
 
# 引数を解析する
args = parser.parse_args()
 
if args.verbose:
    print('Hello')
else:
    print('こんにちは')

実行結果

$ python argparseTest.py
こんにちは
$ python argparseTest.py -v
Hello
$ python argparseTest.py -h
usage: Demonstration of argparser
 
description
 
optional arguments:
  -h, --help     show this help message and exit
  -v, --verbose  select mode
 
end

このサンプルコードではadd_argmentの引数のactionの項目に「store_true」を指定しています。

引数に「-v」もしくは「–-vebose」の引数があれば「Hello」と出力表示され、なければ「こんにちは」と出力表示されるようになっています。

ヘルプの表示には特に影響はありません。

requiredについて

オプション引数の省略をするかどうかをrequiredの項目で指定します。位置引数は省略が出来ないので、オプション引数に対して指定します。

省略不可とした場合に、該当のオプション引数を指定しなければ「error: the following arguments are required」とエラーが出力表示されます。

それではサンプルコードを確認していきましょう。

import argparse
 
# パーサーを作る
parser = argparse.ArgumentParser(
        prog='argparseTest', # プログラム名
        usage='Demonstration of argparser', # プログラムの利用方法
        description='description', # 引数のヘルプの前に表示
        epilog='end', # 引数のヘルプの後で表示
        add_help=True, # -h/–help オプションの追加
        )
 
# 引数の追加
parser.add_argument('-v', '--verbose', help='select mode',
                    action='store_true',
                    required=True)
 
# 引数を解析する
args = parser.parse_args()
 
if args.verbose:
    print('Hello')
else:
    print('こんにちは')

実行結果

$ python argparseTest.py
usage: Demonstration of argparser
argparseTest: error: the following arguments are required: -v/--verbose
$ python argparseTest.py -v
Hello
$ python argparseTest.py -h
usage: Demonstration of argparser
 
description
 
optional arguments:
  -h, --help     show this help message and exit
  -v, --verbose  select mode
 
end

このサンプルコードではオプション引数の「 -v, –-verbose 」のrequiredの項目をTrueに指定して、省略を出来ないようにしています。

実行時に引数の指定をしない場合は、「argparseTest: error: the following arguments are required: -v/–-verbose」(引数が必要だ)とエラーが出力されています。

指定通り引数を指定した場合は、処理が実行され「Hello」が表示されています。

こちらもヘルプの表示には反映されていません。

typeについて

引数は何も指定をしなければ、文字列として扱われます

引数を数値として扱いたい場合などはtypeの項目で指定します。typeの項目で扱いたい型を指定すると、指定した型で処理を行うことができます。

指定した型と異なる引数を指定すると、「error: argument」とエラーが出力表示されます。それではサンプルコードで確認しましょう。

import argparse
 
# パーサーを作る
parser = argparse.ArgumentParser(
            prog='argparseTest', # プログラム名
            usage='Demonstration of argparser', # プログラムの利用方法
            description='description', # 引数のヘルプの前に表示
            epilog='end', # 引数のヘルプの後で表示
            add_help=True, # -h/–help オプションの追加
            )
 
# 引数の追加
parser.add_argument('-v', '--verbose', help='select mode',
                    action='store_true')
parser.add_argument('i', help='integer',
                    type=int)
 
# 引数を解析する
args = parser.parse_args()
 
if args.verbose:
    if args.i % 2 == 1:
        print(str(args.i) + ' : Odd')
    else:
        print(str(args.i) + ' : Even')
else:
    if args.i % 2 == 1:
        print(str(args.i) + ' : 奇数')
    else:
        print(str(args.i) + ' : 偶数')

実行結果

$ python argparseTest.py 3
3 : 奇数
$ python argparseTest.py 3.0
usage: Demonstration of argparser
argparseTest: error: argument i: invalid int value: '3.0'
$ python argparseTest.py 3 -v
3 : Odd
$ python argparseTest.py -h
usage: Demonstration of argparser
 
description
 
positional arguments:
  i              integer
 
optional arguments:
  -h, --help     show this help message and exit
  -v, --verbose  select mode
 
end

このサンプルコードではadd_argumentメソッドの位置引数「i」をtypeの項目でintに指定しています。指定通りに引数にint型を指定すると処理が実行されています。

指定に反して引数にfloat型を指定するとエラーが発生し、「argparseTest: error: argument i: invalid int value: ‘3.0’」(無効なint型の値だ)と出力表示されています。

ヘルプの表示では位置変数(positional arguments)にnameとhelpの項目でそれぞれ指定した内容が表示されています。

引数ありでargparseを使う方法②

ここまで紹介してきた引数の扱い方で全体の半分程度になります。

ここからは、

引数説明
choises引数として許される値の指定
nargs引数の数の指定
default引数がなかった場合に生成される値
metavarメッセージで表示される引数の名前
について、解説します。より実用的なものが増えてきますが、頭のなかで整理しながら学習していきましょう。

choicesについて

引数には許される値を指定することができ、choicesの項目で指定します。

choicesの項目で指定した以外の値を指定すると、エラー「error: argument」が出力表示されます。それではサンプルコードを確認していきましょう。

import argparse
 
# パーサーを作る
parser = argparse.ArgumentParser(
            prog='argparseTest', # プログラム名
            usage='Demonstration of argparser', # プログラムの利用方法
            description='description', # 引数のヘルプの前に表示
            epilog='end', # 引数のヘルプの後で表示
            add_help=True, # -h/–help オプションの追加
            )
 
# 引数の追加
parser.add_argument('-v', '--verbose', help='select mode',
                    type=int,
                    choices=[0,1])
parser.add_argument('i', help='integer',
                    type=int)
 
# 引数を解析する
args = parser.parse_args()
 
if args.verbose == 0:
    if args.i % 2 == 1:
        print(str(args.i) + ' : Odd')
    else:
        print(str(args.i) + ' : Even')
elif args.verbose == 1:
    if args.i % 2 == 1:
        print(str(args.i) + ' : 奇数')
    else:
        print(str(args.i) + ' : 偶数')

実行結果

$ python argparseTest.py 3 -v 0
3 : Odd
$ python argparseTest.py 3 -v 1
3 : 奇数
$ python argparseTest.py 3 -v 2
usage: Demonstration of argparser
argparseTest: error: argument -v/--verbose: invalid choice: 2 (choose from 0, 1)
$ python argparseTest.py -h
usage: Demonstration of argparser
 
description
 
positional arguments:
  i                     integer
 
optional arguments:
  -h, --help            show this help message and exit
  -v {0,1}, --verbose {0,1}
                        select mode
 
end

このサンプルコードではadd_argmentメソッドのオプション引数「-v, –-verbose」にchoisesの項目を指定しています。

choisesの項目でリストから値を選べるように指定しています。

「-v, –-verbose」をint型に指定し、0(ゼロ)か1か選ぶように指定しています。実行結果を確認するとリストの0(ゼロ)か1か選んだ場合は処理を実行しています。

リスト以外の値を選んだ場合はエラーが発生し、「argparseTest: error: argument -v/–verbose: invalid choice: 2 (choose from 0, 1)」と出力表示されています。

ヘルプの表示でも選べる値が表示されるようになっています。

nargsについて

引数の数を指定する場合はnargsの項目で指定します。

指定した数以外で指定すると、エラー「error: the following arguments are required」が表示されます。

サンプルコードで確認していきましょう。

import argparse
 
# パーサーを作る
parser = argparse.ArgumentParser(
            prog='argparseTest', # プログラム名
            usage='Demonstration of argparser', # プログラムの利用方法
            description='description', # 引数のヘルプの前に表示
            epilog='end', # 引数のヘルプの後で表示
            add_help=True, # -h/–help オプションの追加
            )
 
# 引数の追加
parser.add_argument('mul', help='multiply',
                    type=float,
                    nargs=2)
 
 
# 引数を解析する
args = parser.parse_args()
 
n1 = args.mul[0]
n2 = args.mul[1]
calc = n1 * n2
print(str(n1) + ' × ' + str(n2) + ' = ' + str(calc))

実行結果

$ python argparseTest.py 3 5
3.0 × 5.0 = 15.0
$ python argparseTest.py 3
usage: Demonstration of argparser
argparseTest: error: the following arguments are required: mul
$ python argparseTest.py -h
usage: Demonstration of argparser
 
description
 
positional arguments:
  mul         multiply
 
optional arguments:
  -h, --help  show this help message and exit
 
end

このサンプルコードではadd_argmentメソッドの位置引数「mul」にnargsの項目を指定しています。nargsの項目に2を指定しています。

また位置引数「mul」はtypeの項目でint型の指定をしています。これらの指定によって位置引数「mul」は処理する際にはint型のリストとして扱うことができています

引数に1つのみ指定した場合はnargsの項目の指定以外となりますので、エラー「argparseTest: error: the following arguments are required: mul」が出力表示されています。

ヘルプの表示には位置引数(positional arguments)として指定した項目が表示されています。

FileTypeについて

コマンドの引数として入力するファイルパス名や出力するファイルパス名を指定することもあります。そんな場合にはadd_argumentメソッドの引数でtypeの項目をargparse.FileType()で指定します。

入力するファイルパス名を指定する場合はargparse.FileType(‘r’)と指定します。出力するファイルパス名を指定する場合はargparse.FileType(‘w’)と指定します。

引数を指定しない場合は、エラー「error: the following arguments are required」が出力表示されます。

それではサンプルコードで確認していきましょう。なお入力するファイルには「infile.txt」、出力するファイルには「outfile.txt」を指定しています。

infile.txt

Hello

実行結果

import argparse
 
# パーサーを作る
parser = argparse.ArgumentParser(
            prog='argparseTest', # プログラム名
            usage='Demonstration of argparser', # プログラムの利用方法
            description='description', # 引数のヘルプの前に表示
            epilog='end', # 引数のヘルプの後で表示
            add_help=True, # -h/–help オプションの追加
            )
 
# 引数の追加
parser.add_argument('infile', help='inputfile',
                    type=argparse.FileType('r'))
parser.add_argument('outfile', help='outputfile',
                    type=argparse.FileType('w'))
 
# 引数を解析する
args = parser.parse_args()
 
message = args.infile.read()
args.infile.close();
args.outfile.write(message + 'n' + 'Good bye')
args.outfile.close()

実行結果

$ python argparseTest.py infile.txt outfile.txt
$ python argparseTest.py
usage: Demonstration of argparser
argparseTest: error: the following arguments are required: infile, outfile
$ python argparseTest.py -h
usage: Demonstration of argparser
 
description
 
positional arguments:
  infile      inputfile
  outfile     outputfile
 
optional arguments:
  -h, --help  show this help message and exit
 
end

outfile.txt

Hello
Good bye

このサンプルコードではadd_argumentメソッドで2つの引数を指定しています。

第1引数のtypeの項目でargparse.FileType(‘r’)と指定して入力ファイルのパス名を指定するようにしています。第2引数のtypeの項目でargparse.FileType(‘w’)と指定して出力ファイルのパス名を指定するようにしています。

引数の指定が指示通りでなければ、「argparseTest: error: the following arguments are required: infile, outfile」のエラーが出力表示されています。

ヘルプの表示では2つの位置引数(positional arguments)が表示されています。

defaultについて

オプション引数を指定しない場合にdefaultの項目で指定した値を使用して処理します。

サンプルコードを確認していきましょう。

import argparse
 
# パーサーを作る
parser = argparse.ArgumentParser(
            prog='argparseTest', # プログラム名
            usage='Demonstration of argparser', # プログラムの利用方法
            description='description', # 引数のヘルプの前に表示
            epilog='end', # 引数のヘルプの後で表示
            add_help=True, # -h/–help オプションの追加
            )
 
# 引数の追加
parser.add_argument('--version', version='%(prog)s 1.0.0',
                    action='version',
                    default=False)
 
# 引数を解析する
args = parser.parse_args()

実行結果

$ python argparseTest.py --version
argparseTest 1.0.0
$ python3 argparseTest.py -h
usage: Demonstration of argparser
 
description
 
optional arguments:
  -h, --help  show this help message and exit
  --version   show program's version number and exit
 
end

このサンプルコードではadd_argumentメソッドのオプション引数「–version」にdefaultの項目を指定しています。またオプション引数「–version」はactionの項目でversionに指定されていますので、version情報を出力表示します。

defaultの項目の値がFalseで指定していますので、「–version」を引数に指定しない場合はversion情報は出力表示されず、指定した場合はversion情報が「1.0.0」と表示されています。

このバージョン情報は自分のアプリケーションにあった数字にしましょう。

ヘルプの表示にはオプション引数(optional arguments)「–version」として表示されています。

metavarについて

ヘルプやエラーの出力時の引数名を設定したい場合、metavarの項目を指定します。

サンプルコードで確認していきましょう。

import argparse
 
# パーサーを作る
parser = argparse.ArgumentParser(
            prog='argparseTest', # プログラム名
            usage='Demonstration of argparser', # プログラムの利用方法
            description='description', # 引数のヘルプの前に表示
            epilog='end', # 引数のヘルプの後で表示
            add_help=True, # -h/–help オプションの追加
            )
 
# 引数の追加
parser.add_argument('-v', '--verbose', help='select mode',
                    action='store_true')
parser.add_argument('i', help='integer',
                    type=int,
                    metavar='int_value')
 
# 引数を解析する
args = parser.parse_args()
 
if args.verbose:
    if args.i % 2 == 1:
        print(str(args.i) + ' : Odd')
    else:
        print(str(args.i) + ' : Even')
else:
    if args.i % 2 == 1:
        print(str(args.i) + ' : 奇数')
    else:
        print(str(args.i) + ' : 偶数')

実行結果

$ python argparseTest.py 3
3 : 奇数
$ python argparseTest.py -h
usage: Demonstration of argparser
 
description
 
positional arguments:
  int_value      integer
 
optional arguments:
  -h, --help     show this help message and exit
  -v, --verbose  select mode
 
end

このサンプルコードではadd_argumentメソッドの位置引数「i」でmetavarの項目を指定しています。

metavarの項目を「int_value」と指定しています。ヘルプの表示を確認すると位置変数(positional arguments)で「int_value」と表示されています。

argparseを使わないで引数をパースする方法

最後にPythonのargparseを使わないで引数をパース(構文解析)する方法について解説します。

標準のsysモジュールを使って引数をパースします。

こちらのサンプルコードを見てみましょう。

import sys

args = sys.argv
print(args)
print(args[1])
print(args[2])

こちらのコードを、argTest.pyという名前で保存して、コマンドラインからこのように実行してみましょう。

python argTest.py python argtest

実行結果

['argTest.py', 'python', 'argtest']
python
argtest

このように、sys.argsでコマンドライン引数を取得することが出来ました。sys.argvについては、以下の記事で詳しく解説していますので、ぜひ参考にしてください!

まとめ

ここでは、argparseモジュールの使い方について説明しました。

argparseモジュールの使うことで自作したPythonファイルを実行する際に、引数の解析を実行し不具合がある場合はエラーを表示して返したり、ヘルプを表示することができます。

またコマンドラインから引数を受け取れると、より本格的な自作コマンドを作っていくことが出来ます。argparseモジュールを使いこなすことができるようにこの記事を何度も参考にして下さいね!

この記事を書いた人

【プロフィール】
DX認定取得事業者に選定されている株式会社SAMURAIのマーケティング・コミュニケーション部が運営。「質の高いIT教育を、すべての人に」をミッションに、IT・プログラミングを学び始めた初学者の方に向け記事を執筆。
累計指導者数4万5,000名以上のプログラミングスクール「侍エンジニア」、累計登録者数1万8,000人以上のオンライン学習サービス「侍テラコヤ」で扱う教材開発のノウハウ、2013年の創業から運営で得た知見に基づき、記事の執筆だけでなく編集・監修も担当しています。
【専門分野】
IT/Web開発/AI・ロボット開発/インフラ開発/ゲーム開発/AI/Webデザイン

目次