Python の subprocess でシェルコマンドを実行する基本

Python スクリプトから外部のシェルコマンドを実行したい場面は意外と多い。ファイルの一括処理、システム情報の取得、他のプログラムとの連携など、Python だけで完結しないタスクでは外部コマンドの力を借りることになる。標準ライブラリの subprocess モジュールは、こうした外部プロセスの実行を安全かつ柔軟に行うための仕組みを提供している。

subprocess.run の基本

subprocess.run() は Python 3.5 で導入された関数で、外部コマンドを実行するための推奨インターフェースだ。コマンドはリスト形式で渡すのが基本となる。

import subprocess

result = subprocess.run(["echo", "Hello, World!"])
print(result.returncode)  # 0

run() は CompletedProcess オブジェクトを返す。returncode が 0 なら正常終了、0 以外ならエラーを意味する。これは Unix のプロセス終了コードの慣習に従ったものだ。

コマンドをリスト形式で渡す理由は、シェルインジェクションを防ぐためにある。各要素が個別の引数として OS に渡されるため、意図しないコマンドが実行されるリスクを減らせる。

import subprocess

# リスト形式（推奨）
subprocess.run(["ls", "-la", "/tmp"])

# 複数の引数も要素ごとに分ける
subprocess.run(["mkdir", "-p", "output/data"])

shell=True の使い方と注意点

パイプやリダイレクトなど、シェルの機能を使いたい場合は shell=True を指定し、コマンドを文字列で渡す。

import subprocess

# パイプを使う例
subprocess.run("ls -la | grep .py", shell=True)

# 環境変数の展開
subprocess.run("echo $HOME", shell=True)

ただし shell=True にはセキュリティ上のリスクが伴う。ユーザー入力をコマンド文字列に埋め込むと、任意のコマンドが実行される可能性がある。

信頼できない入力を扱う場面では shell=True を避け、リスト形式を使うべきだ。パイプが必要な場合も、Python 側で複数の subprocess.run() をつなぐことで安全に実現できる。

check=True でエラーを検出する

デフォルトでは、外部コマンドが失敗しても run() は例外を投げない。returncode を自分で確認する必要がある。check=True を指定すると、コマンドが非ゼロの終了コードを返した場合に CalledProcessError が発生するようになる。

import subprocess

try:
    subprocess.run(["ls", "/nonexistent"], check=True)
except subprocess.CalledProcessError as e:
    print(f"コマンドが失敗: 終了コード {e.returncode}")

$ python app.py
ls: /nonexistent: No such file or directory
コマンドが失敗: 終了コード 2

check=True を付けておけば、コマンドの失敗を見落とすことがなくなる。スクリプトの途中で外部コマンドが失敗したのに後続処理が走ってしまう、という事故を防げるため、特に理由がなければ付けておくのが無難だ。

タイムアウトの設定

外部コマンドが応答しなくなった場合に備えて、timeout パラメータで制限時間を設けられる。指定した秒数を超えるとプロセスが強制終了され、TimeoutExpired 例外が発生する。

import subprocess

try:
    subprocess.run(["sleep", "10"], timeout=3)
except subprocess.TimeoutExpired:
    print("タイムアウト: コマンドが3秒以内に完了しなかった")

ネットワーク通信を伴うコマンドや、処理時間が予測できないコマンドを実行する際には、タイムアウトを設定しておくとプログラムがハングアップするのを防げる。

CompletedProcess の属性

subprocess.run() が返す CompletedProcess オブジェクトには、実行結果に関する情報がまとまっている。

stdout と stderr はデフォルトでは None になっており、出力をキャプチャするには追加のオプションが必要になる。出力の取得方法については次の記事で詳しく扱う。

古い API との関係

subprocess モジュールには call()、check_call()、check_output() といった古い関数も残っている。これらは Python 3.5 より前に使われていたもので、現在は run() に統一することが推奨されている。

既存のコードで call() や os.system() を見かけたら、subprocess.run() に書き換えることを検討するとよいだろう。run() のほうがパラメータが統一されており、エラーハンドリングも柔軟に行える。