Pythonで外部コマンドを実行したい場合は、subprocessを利用するのがおすすめです。
この記事では、Pythonのsubprocessの使い方を初心者向けに解説します。subprocess.run()の基本構文から、stdout・stderrによる出力取得、subprocess.PIPEの使い方、利用時の注意点まで分かりやすく紹介します。
「PythonからGitやDockerを操作したい」「CLIツールをPythonで自動化したい」という方にも役立つ内容になっているので、ぜひ参考にしてください。
Pythonのsubprocessとは
subprocessは、Pythonから外部コマンドや別プログラムを実行するための標準ライブラリです。ターミナルやコマンドプロンプトで実行する「ls」「dir」「git」などのコマンドを、Pythonコード内から実行できます。
特にPythonのsubprocess.run()を使うと、コマンドの実行から実行結果の取得までを簡単に行えるのが特徴です。標準出力（stdout）や標準エラー（stderr）も取得できるため、実務ではログ確認やエラー処理にも活用されています。
以前はos.system()を使うケースもありましたが、現在のPythonでは、より安全かつ柔軟に扱えるsubprocessが主流になっています。
subprocess.runとos.systemとの違い
subprocess.run()とos.system()は、どちらもPythonから外部コマンドを実行するための機能ですが、現在はsubprocess.run()を利用するのが一般的です。
os.system()はシンプルにコマンドを実行できる一方で、実行結果を取得しづらいというデメリットがあります。また、シェル経由でコマンドを実行するため、安全性の面でも注意が必要です。
一方、subprocess.run()は、実行結果やエラー内容を取得できるほか、タイムアウト設定やエラー検知なども柔軟に行えます。さらに、コマンドと引数をリスト形式で安全に渡せるため、コマンドインジェクションのリスクも軽減できます。
これからPythonを学びはじめる方には、Python入門講座の活用がおすすめです。詳しくはこちらを参考にしてください。
Pythonでsubprocessが使われる具体的なシーン
subprocessは、Pythonから外部コマンドやCLIツールを操作したい場面でよく利用されます。特に実務では、ターミナルで実行している作業をPythonで自動化したいケースが多く、業務効率化や運用自動化でも活用されています。
たとえば、以下のようなシーンで利用されることがあります。
- Gitコマンドを実行してソースコードを自動取得する
- Dockerコマンドを実行してコンテナを操作する
- サーバー監視コマンドを定期実行して状態を確認する
- バッチ処理を自動実行する
- ログ解析コマンドを実行してエラーを抽出する
- ffmpegを利用して動画変換を自動化する
- AWS CLIを実行してクラウド環境を操作する
このように、Pythonのsubprocessは「CLIツールをPythonでまとめて操作する」用途で非常によく利用されています。Python単体では難しい処理でも、既存のコマンドラインツールと組み合わせることで柔軟な自動化を実現できる点が大きな特徴です。
Pythonでsubprocess.runを使う方法
Pythonのsubprocessを利用する際に、最もよく使われるのがsubprocess.run()です。ここでは、subprocess.run()の基本構文やよく使う引数、実際にコマンドを実行する方法を確認していきましょう。
- subprocess.runの基本構文
- subprocess.runでよく使う引数一覧
- 戻り値CompletedProcessの確認方法
- check=Trueによるエラー検知
①subprocess.runの基本構文
Pythonのsubprocess.run()の基本構文は、次のようになります。
import subprocess
subprocess.run([“コマンド名”, “引数”])
ターミナルでスペース区切りで入力するコマンドを、Pythonではリスト形式で渡すのがポイントです。
たとえば、「Hello」と表示するechoコマンドを実行する場合は、Pythonで次のように記述します。
import subprocess
subprocess.run([“echo”, “Hello”])
Hello
このように、Pythonのsubprocess.run()を使うと、Pythonから簡単に外部コマンドを実行できます。
②subprocess.runでよく使う引数一覧
Pythonのsubprocess.run()では、引数を追加することで実行結果の取得やエラー処理などを柔軟に制御できます。代表的な引数は次のとおりです。
| 引数 | 内容 | 主な用途 |
|---|---|---|
| capture_output=True | 標準出力・標準エラーを取得する | 実行結果をPython側で扱う |
| text=True | 出力を文字列として取得する | 日本語や文字列操作を行う |
| check=True | エラー時に例外を発生させる | エラー検知 |
| shell=True | シェル経由でコマンドを実行する | Windowsコマンド実行 |
| timeout=秒数 | 一定時間で処理を停止する | フリーズ防止 |
| encoding=”utf-8″ | 文字コードを指定する | 文字化け対策 |
| input=”値” | 標準入力へ値を渡す | 入力付きコマンド実行 |
Pythonの実務においては、実行結果を取得したい場合はcapture_output=True、文字列として扱いたい場合はtext=Trueを組み合わせて利用するケースが一般的になっています。
③戻り値CompletedProcessの確認方法
Pythonのsubprocess.run()を実行すると、戻り値としてCompletedProcessオブジェクトが返されます。CompletedProcessには、実行したコマンドや終了コード、実行結果などが保存されており、コマンド実行後の情報を確認する際に利用します。
サンプルコードは次のとおりです。
import subprocess
result = subprocess.run(
[“echo”, “Hello”],
capture_output=True,
text=True
)
print(result)
print(result.stdout)
print(result.returncode)
※サンプルコードをコピーして試す場合は、全角スペースをタブに置き換えてから実行してください。
【実行結果】
CompletedProcess(args=[‘echo’, ‘Hello’], returncode=0, stdout=’Hello\n’, stderr=”)
Hello
0
このように、CompletedProcessを利用すると、コマンド実行結果やエラー状況をPython側で確認できます。Pythonの実務では、ログ取得やエラー判定などで頻繁に利用されます。
④check=Trueによるエラー検知
Pythonのsubprocess.run()では、check=Trueを指定することで、コマンド実行時にエラーが発生した場合に例外を発生させることが可能です。
通常はコマンドが失敗してもPythonの処理は継続されますが、check=Trueを付けるとエラーを検知しやすくなるため、実務でもよく利用されています。
たとえば、存在しないコマンドを実行すると次のようになります。
import subprocess
subprocess.run(
[“ls”, “not_found_file”],
check=True
)
subprocess.CalledProcessError
subprocessで標準出力と標準エラーを取得するには
Pythonのsubprocess.run()では、コマンドを実行するだけでなく、実行結果やエラー内容を取得できます。ここでは、コマンドの出力結果をPython側で利用したい場合や、エラー内容をログとして保存したい場合に役立つ方法について解説します。
- stdoutで実行結果を取得する
- stderrでエラー内容を確認する
- text=Trueとencoding指定の違い
- Windows環境で文字化けを防ぐ方法
①stdoutで実行結果を取得する
stdoutを利用すると、コマンドの実行結果をPython側で取得できます。通常、コマンドの実行結果はターミナルへ表示されますが、stdoutを使うことで、実行結果を変数へ保存して処理できるようになります。
サンプルコードは次のとおりです。
import subprocess
result = subprocess.run(
[“echo”, “Hello”],
capture_output=True,
text=True
)
print(result.stdout)
Hello
②stderrでエラー内容を確認する
stderrを利用すると、コマンド実行時に発生したエラー内容をPython側で取得できます。Pythonの実務では、エラーログを保存したり、異常終了の原因を確認したりする場面でよく利用されます。
たとえば、存在しないファイルを指定してlsコマンドを実行するサンプルは次のとおりです。
import subprocess
result = subprocess.run(
[“ls”, “sample_file”],
capture_output=True,
text=True
)
print(result.stderr)
ls: cannot access ‘sample_file’: No such file or directory
③text=Trueとencoding指定の違い
subprocess.run()のtext=Trueは、コマンドの実行結果をPythonの文字列として取得するための設定です。指定しない場合、実行結果は「バイト列（bytes型）」として返されます。
次のようにtext=Trueを指定すると、文字列として扱えるようになります。
import subprocess
result = subprocess.run(
[“echo”, “Hello”],
capture_output=True,
text=True
)
print(result.stdout)
一方、encodingは文字コードを指定するための設定です。特にWindows環境では、日本語を含む出力結果が文字化けすることがあるため、Python側で文字コードを明示的に指定するケースがあります。
import subprocess
result = subprocess.run(
[“dir”],
shell=True,
capture_output=True,
text=True,
encoding=”cp932″
)
上のサンプルコードでは、Windows日本語環境で利用されるcp932を指定しています。
つまり、text=Trueは「文字列として扱う設定」、encodingは「どの文字コードで変換するかを指定する設定」です。日本語を扱う場合は、両方を組み合わせて利用するケースがよくあります。
④Windows環境で文字化けを防ぐ方法
Windows環境でPythonのsubprocess.run()を利用する場合、日本語の実行結果が文字化けすることがあります。これは、WindowsのコマンドプロンプトがUTF-8ではなく、cp932（Shift-JIS系）という文字コードを利用しているケースが多いためです。
次のようにdirコマンドの結果を取得すると、環境によっては日本語が正しく表示されないことがあります。
import subprocess
result = subprocess.run(
[“dir”],
shell=True,
capture_output=True,
text=True
)
print(result.stdout)
このような場合は、encodingを指定することで文字化けを防げます。
import subprocess
result = subprocess.run(
[“dir”],
shell=True,
capture_output=True,
text=True,
encoding=”cp932″
)
print(result.stdout)
WindowsのPython環境ではCLIツールやログ出力で日本語を扱うケースも多いため、text=Trueとあわせてencoding=”cp932″を指定する方法を覚えておくと便利です。
subprocess.PIPEの使い方
subprocess.PIPEは、コマンドの実行結果や入力データをPython側で受け渡しするための仕組みです。簡単にいうと、「コマンドとPythonをつなぐ通路」のような役割があります。
たとえばコマンドの実行結果を取得する場合は、次のようにstdout=subprocess.PIPEを指定します。
import subprocess
result = subprocess.run(
[“echo”, “Hello”],
stdout=subprocess.PIPE,
text=True
)
print(result.stdout)
このコードでは、stdout=subprocess.PIPEを指定することで、コマンドの実行結果をPython側で取得しています。取得した内容はresult.stdoutに格納されるため、文字列として利用できます。
Pythonでsubprocessを利用する際の注意点
Pythonのsubprocessは非常に便利なライブラリですが、使い方を誤るとセキュリティリスクやプログラム停止の原因になることがあります。ここでは、Pythonのsubprocessを安全に利用するために知っておきたい注意点を解説します。
- shell=Trueにはリスクがある
- コマンドインジェクションに注意
- timeout設定でフリーズを防ぐ
①shell=Trueにはリスクがある
Pythonのsubprocess.run()では、shell=Trueを指定することで、シェル経由でコマンドを実行できます。Windowsのdirコマンドなど、一部のコマンドを実行する際に利用される方法です。
ただし、shell=Trueを利用すると、シェルがコマンド文字列を解釈するため、意図しないコマンドまで実行されるリスクがあります。特に、ユーザー入力を含むコマンドをそのまま実行すると、セキュリティ上の問題につながる可能性があります。
そのため、特別な理由がない限りはshell=Trueを使わず、コマンドと引数をリスト形式で渡す方法が推奨されています。
②コマンドインジェクションに注意
コマンドインジェクションとは、悪意のある入力によって、想定外のコマンドを実行されてしまう攻撃のことです。Pythonのsubprocessで外部入力を扱う場合は、特に注意が必要です。
たとえばユーザーが入力した文字列をPython側でそのままコマンドへ結合すると、不正なコマンドまで実行される可能性があります。shell=Trueと組み合わせると、さらにリスクが高くなります。
Pythonのsubprocessを安全に利用するためには、コマンドを文字列結合せず、リスト形式で引数を渡す方法が重要です。また、ユーザー入力を利用する場合は、入力値の検証を行うことも大切です。
③timeout設定でフリーズを防ぐ
Pythonのsubprocess.run()で実行したコマンドは、処理内容によっては終了までに長時間かかることがあります。場合によっては、処理が停止したまま戻ってこないケースもあるため注意が必要です。
このような状況を防ぐために利用されるのがtimeoutです。timeoutを指定すると、一定時間を超えた場合に処理を停止できます。
外部APIを利用するCLIツールや大量データを処理するコマンドでは、想定以上に処理時間が延びることも珍しくありません。プログラム全体の停止を防ぐためにも、実務ではtimeoutを設定しておくと安心です。
近年では、生成AIを活用したAIコーディングも注目を集めています。こちらで詳しく解説しているので、あわせて参考にしてください。
Pythonを体系的に学べるおすすめのセミナー
Pythonを実務で活用したい方には、Pythonを体系的に学べる「Python基礎セミナー講習」の受講がおすすめです。初心者向けに構成されているため、プログラミング経験が少ない方でも基礎から段階的に学習できます。
Pythonの基礎文法やライブラリの使い方はもちろん、Webスクレイピング、データ分析、Excel自動化、画像処理、AIプログラム実装など、実務につながる内容まで幅広く学べるのが特徴です。また、エラー解決の考え方やPythonを使った業務効率化についても学習できます。
実際に手を動かしながら学べるカリキュラムになっているため、「独学では理解しづらかった」「何から学べばよいか分からない」という方にも適しています。subprocessのような実務で役立つライブラリを含め、Pythonスキルを体系的に身につけたい方におすすめです。
| セミナー名 | Python基礎セミナー講習 |
|---|---|
| 運営元 | GETT Proskill（ゲット プロスキル） |
| 価格(税込) | 29,700円〜 |
| 受講期間 | 2日間 |
| 受講形式 | 対面（東京・名古屋・大阪）・ライブウェビナー・eラーニング |
Pythonのsubprocessで外部コマンド実行を使いこなそう
subprocessを利用すると、Pythonから外部コマンドを実行できるようになり、CLIツールとの連携や業務自動化を効率的に行えます。特にsubprocess.run()を使えば、コマンド実行だけでなく、標準出力やエラー内容の取得も簡単に実装可能です。
subprocessは、Git操作やサーバー管理、バッチ処理、AWS CLI実行など、実務でも活用される重要なライブラリです。ぜひ基本的な使い方を身につけ、Pythonによる外部コマンド実行や業務自動化へ活用していきましょう。
