Pythonでスクリプトを書くようになると、コマンドライン引数の扱いは避けて通れません。
ファイル名や設定値を外から渡せるようになると、コードの再利用性や実用度が一気に上がります。
本記事では、初心者が最初に知っておくべきsys.argvとコマンドライン引数の基本から、実践的な使い方、他の方法との比較まで、順を追ってていねいに解説します。
Pythonのコマンドライン引数とは
コマンドライン引数の基本と仕組み
プログラムをコマンドラインから実行するとき、実行コマンドの後ろに続けて書く値が「コマンドライン引数」です。
Pythonでは、渡されたコマンドライン引数はsys.argvというリストにまとめて格納されます。
たとえば、次のように実行したとします。
python hello.py Alice 25
このとき、Pythonプログラムの内部では次のようなリストが自動的に用意されます。
sys.argv[0]… 実行ファイル名(この例では"hello.py")sys.argv[1]… 1番目の引数"Alice"sys.argv[2]… 2番目の引数"25"
Python側から見ると、コマンドライン引数は「文字列のリスト」として渡されるという点がもっとも重要です。
なぜPythonでコマンドライン引数を使うのか
コマンドライン引数を使うと、同じプログラムをさまざまな条件で使い回せるようになります。
たとえば次のような場面です。
- 画像ファイルのパスを引数として渡し、画像を一括で加工する
- ログファイルのパスと日付を渡し、その条件でフィルタリングする
- 数値パラメータ(回数、しきい値など)を外から指定して挙動を切り替える
これらを毎回プログラム内で書き換えるのは非常に非効率です。
コマンドライン引数を使えば、「プログラムは固定のまま・渡す値だけ変える」ことができるため、自動化やスクリプト化との相性がとても良くなります。
また、シェルスクリプトやバッチファイルからPythonスクリプトを呼び出すときにも、引数で値を渡せるので、他のツールとの連携がしやすくなります。
Python初心者が押さえるべきポイント
Python初心者の段階では、次の3点を押さえておくと理解がスムーズです。
1つ目は、すべてのコマンドライン引数は「文字列」として渡されるという点です。
数値として使いたいときはintやfloatなどで明示的に変換する必要があります。
2つ目は、sys.argv[0]にはスクリプト自身のファイル名が入ることです。
最初の引数はsys.argv[1]から始まるので、インデックスを1つずらして考える必要があります。
3つ目は、引数の数が足りないときに、そのままsys.argv[1]などへアクセスするとエラーになることです。
実用的なスクリプトでは、後ほど説明するように「引数の数チェック」や「使い方メッセージ」の出力を行うのが一般的です。
sys.argvの基本と使い方
sysモジュールとsys.argvとは
sysモジュールは、Pythonインタプリタに関する情報や機能を提供する標準ライブラリです。
その中に含まれているargvという変数が、コマンドライン引数を格納しているリストです。
利用するためには、スクリプトの先頭付近でimport sysと書きます。
インポートをしないとsys.argvは使えない点に注意してください。
sys.argvの構造
sys.argvは、「文字列のリスト」です。
その中身には、実行したときのコマンドラインが、空白区切りで1つずつ格納されます。
リストの構造は次のようなイメージです。
たとえば、コマンドラインで次のように入力します。
python script.py foo bar
このときのsys.argvは次のようになります。
sys.argv[0]… “script.py”sys.argv[1]… “foo”sys.argv[2]… “bar”
空白で区切られた単位ごとに1要素になるため、スペースを含む文字列を1つの引数として扱いたい場合には、シェル側で引用符(ダブルクォートやシングルクォート)で囲む必要があります。
sys.argvの簡単なサンプルコード
ここでは、渡されたコマンドライン引数をそのまま表示するシンプルな例を示します。
Pythonファイル名をshow_argv.pyとします。
# show_argv.py
import sys # sysモジュールをインポート
def main():
# sys.argvの中身をそのまま表示
print("sys.argv の中身:", sys.argv)
# 個別の要素も表示してみる
# 長さが1以上ある場合は、スクリプト名を表示
if len(sys.argv) >= 1:
print("スクリプト名:", sys.argv[0])
# 長さが2以上ある場合は、1番目の引数を表示
if len(sys.argv) >= 2:
print("1番目の引数:", sys.argv[1])
# 長さが3以上ある場合は、2番目の引数を表示
if len(sys.argv) >= 3:
print("2番目の引数:", sys.argv[2])
if __name__ == "__main__":
main()このスクリプトを次のように実行してみます。
python show_argv.py apple banana
sys.argv の中身: ['show_argv.py', 'apple', 'banana']
スクリプト名: show_argv.py
1番目の引数: apple
2番目の引数: bananaこの例から、引数はすべて文字列としてリストに入っていることと、スクリプト自身のファイル名も0番目として含まれることを確認できます。
コマンドライン引数の数をチェックする方法
実際にスクリプトを作ると、「最低限これだけの引数が必要」という前提が生じます。
たとえば「1つのファイルパスが必須」などです。
そのような場合には、len(sys.argv)を使って、引数の数をチェックします。
次のサンプルでは、「引数が1つだけ必要」という前提でチェックを行います。
# arg_check.py
import sys
def main():
# sys.argv[0] はスクリプト名なので、
# 引数が1つ必要であれば、全体の長さは 2 である必要がある
if len(sys.argv) != 2:
print("使い方: python arg_check.py <名前>")
# 終了コード1で異常終了を表す
sys.exit(1)
# ここに来るのは、引数の数が正しい場合のみ
name = sys.argv[1]
print(f"こんにちは、{name}さん！")
if __name__ == "__main__":
main()実行例を2パターン見てみます。
引数なしで実行した場合:
$ python arg_check.py
使い方: python arg_check.py <名前>正しい数の引数を渡した場合:
$ python arg_check.py Taro
こんにちは、Taroさん！このように、引数の数が想定と違う場合には、使い方(Usage)を表示して終了するのが一般的です。
終了コードとしてsys.exit(1)のように0以外を返すと、外部ツールから呼び出す場合にも「エラーがあった」と判断しやすくなります。
実践的なコマンドライン引数の活用例
文字列や数値を引数で受け取る方法
実用的なスクリプトでは、ユーザー名などの文字列だけでなく、回数や秒数などの数値をコマンドライン引数で受け取りたい場面が多くあります。
先ほども触れましたが、sys.argvはすべて文字列なので、数値として使う場合には型変換が必須です。
次のサンプルでは、挨拶メッセージを指定回数だけ表示する簡単なスクリプトを作成します。
# repeat_hello.py
import sys
def main():
# 引数が2つ必要:
# 1つ目: 名前(文字列)
# 2つ目: 回数(数値)
if len(sys.argv) != 3:
print("使い方: python repeat_hello.py <名前> <回数>")
sys.exit(1)
name = sys.argv[1]
count_str = sys.argv[2]
try:
# 文字列を整数に変換
count = int(count_str)
except ValueError:
print("回数には整数を指定してください。")
sys.exit(1)
for i in range(count):
print(f"{i + 1}回目: こんにちは、{name}さん！")
if __name__ == "__main__":
main()$ python repeat_hello.py Hanako 3
1回目: こんにちは、Hanakoさん！
2回目: こんにちは、Hanakoさん！
3回目: こんにちは、Hanakoさん！この例から、文字列引数はそのまま使い、数値はint()で変換するという基本パターンをつかんでおくとよいでしょう。
ファイル名やパスを引数で受け取る方法
次は、テキストファイル名を引数で受け取り、その内容を表示する例です。
ファイル名やパスをコマンドライン引数で受け取ると、さまざまなファイルを同じスクリプトで処理できるようになります。
# read_file.py
import sys
def main():
if len(sys.argv) != 2:
print("使い方: python read_file.py <ファイルパス>")
sys.exit(1)
filepath = sys.argv[1]
try:
# 指定されたパスのファイルを開く
with open(filepath, "r", encoding="utf-8") as f:
content = f.read()
except FileNotFoundError:
print(f"ファイルが見つかりません: {filepath}")
sys.exit(1)
except OSError as e:
# その他の入出力エラーをまとめて処理
print(f"ファイルを読み込めませんでした: {e}")
sys.exit(1)
print("=== ファイルの内容 ===")
print(content)
if __name__ == "__main__":
main()$ python read_file.py sample.txt
=== ファイルの内容 ===
(ここに sample.txt の内容が表示されます)このように、ファイル関連のスクリプトでは、パスをコマンドライン引数で指定できるようにするのが一般的です。
Windowsでスペースを含むパスを使う場合は、シェル側で"C:\Program Files..."のように引用符で囲む必要がある点にも注意してください。
複数の引数を扱うサンプル
ここでは、簡易的な電卓プログラムを例にして、複数の引数をどのように解釈して処理するかを見ていきます。
# calc.py
import sys
def main():
# 必須引数は3つ:
# 1つ目: 操作種別("add" or "sub")
# 2つ目: 左の数値
# 3つ目: 右の数値
if len(sys.argv) != 4:
print("使い方: python calc.py <add|sub> <左の数> <右の数>")
sys.exit(1)
op = sys.argv[1]
left_str = sys.argv[2]
right_str = sys.argv[3]
try:
left = float(left_str)
right = float(right_str)
except ValueError:
print("数値には整数または小数を指定してください。")
sys.exit(1)
if op == "add":
result = left + right
elif op == "sub":
result = left - right
else:
print("サポートされていない操作です。add または sub を指定してください。")
sys.exit(1)
print(f"結果: {result}")
if __name__ == "__main__":
main()$ python calc.py add 10 3.5
結果: 13.5
$ python calc.py sub 10 3
結果: 7.0このように、複数の引数を「役割ごと」に分解して解釈することで、簡単なコマンドラインツールを作成できるようになります。
エラー処理と使い方のベストプラクティス
実際の開発では、「エラー時にどう振る舞うか」をあらかじめ決めておくことが大切です。
sys.argvを使うスクリプトにおける、代表的なベストプラクティスをいくつか挙げます。
1つ目は、引数の数を必ずチェックすることです。
足りない場合や多すぎる場合には、使い方(Usage)を表示して終了するようにします。
これにより、ユーザーは「何をどう指定すればよいか」をすぐに理解できます。
2つ目は、型変換やファイルアクセスの失敗を例外で拾い、意味のあるメッセージを出すことです。
そのままトレースバックが出るよりも、「数値を指定してください」「ファイルが見つかりません」など、ユーザーが次に何をすればよいか判断しやすいメッセージを出した方が親切です。
3つ目は、エラー時には0以外の終了コードで終了することです。
sys.exit(1)やsys.exit(2)などを用いると、シェルスクリプトやCIツール側から「成功か失敗か」を判定しやすくなります。
最後に、長く複雑になってきたら、後述するargparseへの移行も検討しましょう。
引数の定義やエラーメッセージ生成を自動で行ってくれるため、大規模になっても管理しやすくなります。
sys.argvと他の方法の比較
sys.argvとinputの違いと使い分け
Pythonで外部から値を受け取る方法として、sys.argvとinput()はよく比較されます。
この2つは役割が少し異なります。
sys.argvは、スクリプトを実行するときに、あらかじめ一括で値を渡す仕組みです。
一度渡した値は、その実行中は変わりません。
自動化スクリプトやバッチ処理との相性が良く、ユーザーとの対話なしに完結します。
一方input()は、プログラムの実行途中でユーザーの入力を待ち受けるための関数です。
コマンドラインから対話的に操作したいときに向いています。
簡単な比較表を示します。
| 観点 | sys.argv | input() |
|---|---|---|
| 値を渡すタイミング | 実行開始時に一括 | 実行中に随時 |
| ユーザーとの対話 | なし(非対話的) | あり(対話的) |
| 自動化・バッチ処理との相性 | 高い | 低い |
| 初心者にとっての理解しやすさ | やや難しい | わかりやすい |
GUIやWebアプリでは別の入力方法(formやボタンなど)を使うことになりますが、シンプルなCLIツールではsys.argvとinput()をうまく使い分けるとよいでしょう。
sys.argvとargparseの違いと特徴
sys.argvは非常にシンプルで直感的ですが、引数が多くなると管理が難しくなるという欠点があります。
たとえば、オプションの有無や、省略可能な引数、デフォルト値、ヘルプメッセージなどをすべて自分で書く必要があります。
この問題を解決するために、Python標準ライブラリにはargparseというモジュールが用意されています。
argparseを使うと、次のようなことが自動で行われます。
- 引数名やオプション名を宣言的に定義できる
- 型(整数、文字列など)を指定すると、自動で変換してくれる
- -h / –helpオプションでヘルプメッセージを自動生成
- 必須・任意の引数や、デフォルト値を簡単に定義できる
非常に簡略化したargparseの例を示します。
# sample_argparse.py
import argparse
def main():
parser = argparse.ArgumentParser(description="argparse のサンプル")
parser.add_argument("name", help="挨拶する相手の名前")
parser.add_argument("-n", "--num", type=int, default=1, help="繰り返す回数")
args = parser.parse_args()
for i in range(args.num):
print(f"{i + 1}回目: こんにちは、{args.name}さん！")
if __name__ == "__main__":
main()$ python sample_argparse.py Hanako -n 3
1回目: こんにちは、Hanakoさん！
2回目: こんにちは、Hanakoさん！
3回目: こんにちは、Hanakoさん！
$ python sample_argparse.py -h
usage: sample_argparse.py [-h] [-n NUM] name
argparse のサンプル
positional arguments:
name 挨拶する相手の名前
options:
-h, --help show this help message and exit
-n NUM, --num NUM 繰り返す回数このように、argparseは「本格的なコマンドラインツール」を作るための強力な仕組みです。
一方で設定項目が多く、初心者にとっては少しハードルが高く感じられるかもしれません。
初心者におすすめの学習ステップとまとめの指針
Python初心者がコマンドライン引数を学ぶ際には、いきなり複雑なargparseに飛び込むよりも、まずはsys.argvの基本をしっかり身につけることをおすすめします。
具体的なステップは次のような流れです。
1つ目のステップとして、input()でユーザーから文字列や数値を受け取り、型変換を行う練習をすると、外部からの入力処理に慣れることができます。
2つ目のステップでは、sys.argvを使って「1つの引数」を受け取るスクリプトを書いてみてください。
たとえば、挨拶の相手の名前を引数で指定するなど、シンプルなもので構いません。
3つ目のステップとして、sys.argvで複数の引数(文字列、数値、ファイルパス)を扱い、引数数チェックやエラー処理も取り入れたスクリプトに発展させます。
この段階で、本記事で紹介した例を手元で実行しつつ、少しずつ改造してみると理解が深まります。
そして4つ目のステップとして、引数が増えてきたり、オプションを扱いたくなったタイミングでargparseに挑戦すると、自然な流れでステップアップできます。
sys.argvは「コマンドライン引数の素顔」を知るための、もっとも良い入口です。
まずはここをしっかり理解しておくことで、その先のargparseや他のライブラリもスムーズに学べるようになります。
まとめ
コマンドライン引数は、Pythonスクリプトを実用的なツールに育てるうえで欠かせない仕組みです。
本記事では、sys.argvの基本構造と使い方、文字列・数値・ファイルパスの実践例、エラー処理の考え方、さらにinputやargparseとの違いを解説しました。
まずはsys.argvで1〜2個の引数を扱う簡単なスクリプトから始め、徐々に複数引数やエラーハンドリングへと発展させてみてください。
その経験が、より高度なコマンドラインツール開発への確かな土台になります。
