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

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

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

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

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

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

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

【著者プロフィール＆本記事の信頼性】

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

⇒プロフィール詳細はコチラ

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

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

sys.argvの仕組み

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

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ですが、本格的なツールを作る上ではいくつかの課題があります。

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

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

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

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

なぜargparseを使うべきか？

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

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

argparseの基本的な使い方

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

1. パーサーの作成: argparse.ArgumentParser()で、引数を解析するためのオブジェクトを作成します。
2. 引数の定義: .add_argument()メソッドを使って、受け付けたい引数の名前や型、ヘルプメッセージなどを定義していきます。
3. 引数の解析: .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が適しているケースとしては、自分しか使わない、引数が1つか2つで固定されている、といったごくごく単純なスクリプトの場合です。

argparseが適しているケースは、上記以外のほとんどすべてのケースです。
特に、他人が使う可能性のあるツールや、少しでも複雑な引数を扱う場合は、迷わずargparseを使いましょう。

初心者がPythonでのコマンドラインなどを効率的に学ぶには

コマンドラインをはじめとするPythonのスキルを効率的に習得するには、プログラミングスクールの活用が最も近道です。

スクールでスキルを高めることにより、今の仕事に活かしたり、副業として高単価な案件を受注できたりするだけでなく、Pythonエンジニアとして転職することも可能になります。

Pythonエンジニアは需要が非常に高いため、それに比例して年収も高くなる傾向にあります。
「今よりも年収を上げたい」「将来性の高い職種であるエンジニアへ転職したい」といった気持ちが強い場合は、プログラミングスクールでPythonの専門スキルを習得しつつ、ポートフォリオ支援や転職支援を受けてエンジニアへ転職する、という道を目指すのもよいでしょう。

なお、「Pythonに強く、受講生からの評判も良いプログラミングスクール」には、以下のようなところがあります。

その他、以下の記事でもPythonのおすすめスクールをまとめていますので、興味のある方は是非参考にしてください。

【厳選】Pythonスクールおすすめ9選！オンラインで学べる安いプログラミングスクール

AI開発やデータ分析、Web開発など幅広い分野で活用されるPython。 需要が急増する中、効率的に学習できるプログラミングスクールを探している人も多いのではないでしょうか。 そこでこの記事では、2025年現在の「Pythonが学べるおすす...

progneer.net

Follow me!