Pythonでのコマンドライン引数の渡し方・受け取り方

Pythonでスクリプトを書いていると、「実行するときに処理対象のファイル名を指定したい」「特定のオプションを付けたときだけデバッグ情報を表示したい」といった、外部から動的に値を渡したい場面が必ず出てきます。

これを実現するのが「コマンドライン引数」です。

コマンドライン引数を使えば、スクリプトのコードを直接書き換えることなく、実行時の挙動を柔軟に制御できます。

この記事では、Pythonでコマンドライン引数を扱うための2つの主要な方法、

シンプルで手軽な sys.argv
高機能で堅牢な argparse（推奨）

について、具体的なサンプルコードを交えながら、それぞれの使い方と特徴を徹底的に解説していきます。

【本記事の信頼性】

執筆者は元エンジニア
大手プログラミングスクールのWebディレクター兼ライターを経験
自らも地元密着型のプログラミングスクールを運営

未経験者におすすめの
プログラミングスクール

RUNTEQ （ランテック）	■Webエンジニアの育成に特化 ■自社開発企業への転職成功率がダントツ ■ハイスキルを求める人に最適
RaiseTech （レイズテック）	■サポートは半永久的 ■単価80万円以上の講師陣 ■AWSやJavaに強い
0円スクール	■受講料完全無料 ■最短1か月で卒業 ■教室への通学も可能

方法①：sys.argv を使った基本的な引数の受け取り方
方法②：argparse を使った高機能な引数の受け取り方（推奨）
【比較】sys.argv vs argparse どちらを使うべきか？
まとめ

方法①：sys.argv を使った基本的な引数の受け取り方

まずは、Pythonの標準ライブラリsysモジュールに含まれるargvを使った最も基本的な方法です。
追加のライブラリをインストールする必要なく、手軽に利用できるのが特徴です。

sys.argvの仕組み

sys.argvは、スクリプト実行時に渡されたコマンドライン引数を格納したリスト（list）です。
このリストの中身には、以下のようなルールがあります。

sys.argv[0]: 実行したスクリプト自身のファイル名
sys.argv[1]: 1番目の引数
sys.argv[2]: 2番目の引数
…

python script.py arg1 arg2 → sys.argv = ['script.py', 'arg1', 'arg2']

このように、インデックス0には必ずスクリプト名が入り、実際の引数はインデックス1から始まることを覚えておくのが重要です。

具体的なコード例

では、実際にsys.argvを使って引数を受け取るスクリプトを作成してみましょう。

show_args.py

import sys

print(f"sys.argvの型: {type(sys.argv)}")
print(f"sys.argvの中身: {sys.argv}")

# リストの要素数（引数の総数）を取得
num_args = len(sys.argv)
print(f"渡された引数の総数（スクリプト名を含む）: {num_args}")

# 引数を一つずつ表示
if num_args > 1:
    print(f"1番目の引数: {sys.argv[1]}")
if num_args > 2:
    print(f"2番目の引数: {sys.argv[2]}")

実行方法と結果

このスクリプトをターミナル（Windowsの場合はコマンドプロンプト）で実行してみます。

実行コマンド

python show_args.py apple banana

実行結果

sys.argvの型: <class 'list'>
sys.argvの中身: ['show_args.py', 'apple', 'banana']
渡された引数の総数（スクリプト名を含む）: 3
1番目の引数: apple
2番目の引数: banana

sys.argvの限界と注意点

手軽なsys.argvですが、本格的なツールを作る上ではいくつかの課題があります。

引数がすべて文字列になる	`sys.argv`で受け取った引数は、たとえ`123`のような数字であっても、すべて文字列型（`str`）として扱われます。数値として計算に使いたい場合は、`int()`や`float()`を使って明示的に型を変換する必要があります。
エラーハンドリングが手動	もし引数が期待した数より少ない場合、存在しないインデックスにアクセスしようとして`IndexError`が発生します。これを避けるには、`len(sys.argv)`で要素数を確認する`if`文を自分で書かなければなりません。
オプションの解析が面倒	`-f`や`--file`のようなオプション（フラグ）を実装しようとすると、自分で引数をループさせて文字列を解析する複雑なコードが必要になります。
ヘルプメッセージがない	スクリプトの使い方を説明するヘルプメッセージ（`-h`や`--help`で表示されるもの）も、自力で作成する必要があります。

これらの課題を解決してくれるのが、次に紹介するargparseモジュールです。

方法②：argparse を使った高機能な引数の受け取り方（推奨）

argparseは、コマンドライン引数を解析するための、より強力で柔軟な標準ライブラリです。

少しでも複雑な引数処理が必要な場合や、他人に使ってもらう可能性があるスクリプトを作成する場合には、argparseの利用を強く推奨します。

なぜargparseを使うべきか？

argparseには、sys.argvの課題を解決する多くのメリットがあります。

ヘルプメッセージの自動生成: -hや--helpオプションを自動で追加し、引数の説明を分かりやすく表示してくれます。
エラーハンドリング: 必須の引数が足りない場合などに、親切なエラーメッセージを自動で表示して終了してくれます。
型変換: 引数の型をintなどに指定すれば、自動で型を変換してくれます。
オプション引数の簡単な定義: -fのような短い形式と--fileのような長い形式のオプションを簡単に定義できます。
デフォルト値: 引数が指定されなかった場合のデフォルト値を簡単に設定できます。

argparseの基本的な使い方

argparseの利用は、以下の3つのステップで行うのが基本です。

パーサーの作成: argparse.ArgumentParser()で、引数を解析するためのオブジェクトを作成します。
引数の定義: .add_argument()メソッドを使って、受け付けたい引数の名前や型、ヘルプメッセージなどを定義していきます。
引数の解析: .parse_args()メソッドを実行し、実際に渡されたコマンドライン引数を解析して、結果をオブジェクトとして取得します。

実践的なコード例

では、これらの機能を使った具体的なスクリプトを見ていきましょう。ユーザー名と年齢を受け取り、指定された回数だけ挨拶を表示するツールを作成します。

greeting_tool.py

import argparse

# 1. パーサーの作成
# descriptionは、-hで表示されるヘルプメッセージの先頭に表示される説明文
parser = argparse.ArgumentParser(description='名前と年齢を受け取り、挨拶を表示するツールです。')

# 2. 引数の定義
# 位置引数 (必須)
parser.add_argument('name', help='挨拶する相手の名前 (文字列)')

# オプション引数
parser.add_argument('-c', '--count', type=int, default=1, help='挨拶を表示する回数 (整数、デフォルト: 1)')
parser.add_argument('-a', '--age', type=int, help='相手の年齢 (整数)')
parser.add_argument('-v', '--verbose', action='store_true', help='詳細な情報を表示する')

# 3. 引数の解析
args = parser.parse_args()

# 解析した引数の利用
for i in range(args.count):
    print(f"({i+1}/{args.count}) Hello, {args.name}!")

if args.age is not None:
    print(f"{args.name}さんの年齢は {args.age}才です。")

if args.verbose:
    print("--- 詳細情報 ---")
    print(f"引数オブジェクト: {args}")

ソースコードの解説

parser.add_argument('name', ...)⇒nameのように-で始まらない引数は「位置引数」となり、基本的に必須の引数として扱われます。

parser.add_argument('-c', '--count', ...)
⇒-や--で始まる引数は「オプション引数」となり、必須ではありません。短い形式と長い形式の両方を定義できます。

type=int
⇒countとage引数にint型を指定。これにより、argparseは渡された文字列を自動で整数に変換してくれます。もし変換に失敗するような文字列（例: abc）が渡されると、エラーを返してくれます。

default=1
⇒count引数が指定されなかった場合、デフォルトで1が使われます。

action='store_true'
⇒-vや--verboseのような、指定されたらTrue、されなければFalseになるだけのフラグ（引数の値を取らないオプション）を定義する際の決まり文句です。

実行方法と結果

このスクリプトを様々な引数で実行してみましょう。

ケース1：ヘルプメッセージを表示する

python greeting_tool.py -h

実行結果

usage: greeting_tool.py [-h] [-c COUNT] [-a AGE] [-v] name

挨拶する相手のツールです。

positional arguments:
  name                  挨拶する相手の名前 (文字列)

options:
  -h, --help            show this help message and exit
  -c COUNT, --count COUNT
                        挨拶を表示する回数 (整数、デフォルト: 1)
  -a AGE, --age AGE     相手の年齢 (整数)
  -v, --verbose         詳細な情報を表示する

このように、定義したhelpメッセージが整形されて表示されます。

ケース2：必須引数とオプションを渡す

python greeting_tool.py Alice --count 3 --age 20 -v

実行結果

(1/3) Hello, Alice!
(2/3) Hello, Alice!
(3/3) Hello, Alice!
Aliceさんの年齢は 20才です。
--- 詳細情報 ---
引数オブジェクト: Namespace(name='Alice', count=3, age=20, verbose=True)

すべての引数が正しく解釈され、プログラムが動作していることが分かります。

ケース3：必須引数が足りない

python greeting_tool.py

実行結果

usage: greeting_tool.py [-h] [-c COUNT] [-a AGE] [-v] name
greeting_tool.py: error: the following arguments are required: name

必須であるname引数が足りないため、argparseが自動でエラーメッセージを表示してくれました。

【比較】sys.argv vs argparse どちらを使うべきか？

両者の特徴をまとめると、以下のようになります。

	`sys.argv`	`argparse`
手軽さ	非常に手軽	少し記述量が増える
ヘルプ機能	なし（自作が必要）	自動生成
エラー処理	手動（`IndexError`など）	自動生成
型変換	手動（`int()`など）	自動
オプション	解析が複雑	簡単に定義可能
推奨度	個人用の単純なスクリプト	ほぼすべてのケースで推奨