Python仮想環境の作り方｜venv・pip・切替と環境確認の手順

※本記事にはPRを含む場合があります。

こんにちは。『脱会社員』脱サラを応援し続けるブログ、運営者の『なかびー』です。

Pythonの教材で「まず仮想環境を作ってください」と書かれていても、作成と有効化の違いが分からず、コマンドを順に貼り付けて終わっていませんか。動いた直後は問題がなくても、別の仕事を始めたときに必要なパッケージが見つからない、インストールしたはずの版が違う、昨日のフォルダーでは動くのに今日のフォルダーでは動かない、と迷いやすいところです。

この記事では標準機能のvenvを使い、project-aとproject-bという二つの練習フォルダーを作ります。Aだけに小さなパッケージを追加し、Bでは見つからないことを確認します。さらにAの依存関係を記録して、別名の環境に再構築します。コマンドの暗記よりも「どのPythonを動かしたか」「どこへ追加したか」「何を残せば作り直せるか」を説明できることが目標です。

確認日は2026年10月4日です。実行検証はLinuxのbash、Python 3.12.14、独立した練習用venvで行いました。WindowsのPowerShell・コマンドプロンプト、macOSの操作例は公式資料に基づく案内で、実機では検証していません。Pythonやpipの表示版は導入方法で変わるため、以下の確認コードで自分の値を記録してください。組織管理PCの設定や、本番プロジェクトの環境をこの練習のために変更する必要はありません。

Python仮想環境で分かれるもの・分かれないものを知る

仮想環境は案件ごとのパッケージ置き場を持つ

venvは、既に導入されているPythonを土台として、プロジェクト用の実行環境をディレクトリに作る標準機能です。例えば集計ツールAはあるライブラリの特定版、試作ツールBは別の版を必要とするとき、二つを同じ場所へ入れると片方の更新がもう片方に影響する可能性があります。AとBに別々のvenvを置けば、通常の設定ではパッケージを追加する場所を分けて扱えます。

大切なのは、venvが別のOSを起動する仮想マシンではないことです。ファイルへのアクセス権、ネットワーク接続、実行するコードの危険性を隔離する仕組みではありません。仮想環境の中でも、コードが読めるファイルや送信できる情報は存在します。知らない配布元のスクリプトを試す安全箱だとは考えず、導入するパッケージや実行内容を確認してください。

Python本体の版も、名前だけで自由に変わるものではありません。Python 3.12からvenvを作るなら、土台になるのはそのPythonです。3.13や別の実装を必要とする案件では、対応するPython本体の準備と選択を先に行います。venvのフォルダー名を「python313」に変えても、Pythonの版が3.13になることはありません。

※表は横にスクロールできます。

「作成」「有効化」「実行」を別の操作として考える

作成は、.venvというディレクトリに必要な構成を用意する操作です。有効化は、今開いているシェルでpythonなどを見つける順番を変える操作です。実行は、選んだPythonで自分のプログラムを動かす操作です。一度作成した環境を翌日使うときは、毎回作り直す必要はありません。新しいターミナルを開いて必要な環境を選び、実行先を確認します。

有効化の後に表示される「(.venv)」は手掛かりですが、決定的な証拠としては不足します。AにもBにも同じ.venvという名前を付けられるため、見た目の接頭辞だけではどちらか分からないからです。確認にはsys.executableとsys.prefixを使います。また、フォルダーを移動しただけでは有効な環境が自動で切り替わるとは限りません。移動と切替を一緒の操作だと思い込まないことが、誤インストールを防ぎます。

有効化は必須ではありません。環境内のPythonをパスで指定すれば、そのPythonを直接実行できます。本記事でもAとBの比較や再作成では、この方法を使います。複数の環境を扱う処理や、有効化スクリプトが許可されていない端末では、明示したパスが分かりやすい選択肢になります。公式のvenvの説明には、作成・有効化・直接実行の関係が示されています。

.venvの中へ成果物を保存しない

練習用のproject-aには、自分が書いたcheck_env.pyや依存関係の記録を置き、その下の.venvは再作成できる環境用と考えます。仕事のCSV、原稿、画像、API設定などを.venvの中へ保存すると、後から環境を作り直す際に必要なファイルまで失う原因になります。実行環境と成果物の置き場を、最初に分けておきましょう。

環境ディレクトリそのものを別PCへコピーして引き継ぐ運用も避けます。内部に絶対パスなどが含まれ、移動後にコマンドが元の場所を参照することがあります。残すのはソースコード、必要なデータの扱い方、Pythonの版、依存関係、実行方法、検算結果です。これらから受け取り側で新しく環境を作る方が、壊れたコピーを調べ続けるより見通しがよくなります。

今回の完成条件を先に決める

この記事の練習では、AとBのsys.prefixが異なり、どちらも仮想環境であること、Aだけでpackaging 25.0が見つかること、記録から作ったAの再構築先でも同じ版が確認できることを完成条件にします。packagingはPythonのバージョン表記などを扱うパッケージで、ここでは依存関係を一つ追加する小例として使います。25.0は今回の検算に使う固定版で、常に最新・最適な版だと勧めるものではありません。

他の教材で既にvenvを作っている場合も、それを流用せず新しい練習フォルダーで始めると、初期状態と追加後の差を見られます。仕事の環境に試しのパッケージを入れる必要はありません。ネットワーク制限のある端末では、管理者の許可された導入方法を確認し、インストールを急がず環境作成と確認までに区切って構いません。

二つのvenvを作り、Pythonと作業場所を確認する

空の親フォルダーから開始する

エクスプローラーやFinderなどで、分かりやすい場所にvenv-lessonという新しい空のフォルダーを作り、その中でターミナルを開いてください。同名のフォルダーが既にある場合は別名を選びます。以下はこの空の親フォルダーを現在地として実行する例です。途中でエラーが出たら、後続コマンドを続ける前に原因を確認します。

WindowsではPythonを起動するコマンドが導入方法によって異なります。まずpy –versionで確認し、pyが使えないがpythonが導入済みの場合はpython –versionを確認します。目的のPythonであることを確かめたうえで、その起動コマンドをvenv作成に使います。次はpyが利用できるWindowsの例です。入力する行に「PS>」のような画面の印は含めません。

py --version
mkdir project-a
mkdir project-b
py -m venv project-a\.venv
py -m venv project-b\.venv

macOSやLinuxでは、Python 3の起動名がpython3である構成を想定します。こちらも先に版を確認します。OS付属のPythonや、別の管理ツールで導入したPythonが複数ある場合、表示された版だけでなく、次の確認スクリプトが出す実行ファイルの場所も記録してください。

python3 --version
mkdir project-a
mkdir project-b
python3 -m venv project-a/.venv
python3 -m venv project-b/.venv

初回の作成が完了すると、Windowsでは.venvの下にScripts、macOS・Linuxではbinなどができます。隠しファイルを表示しない設定では.venvが見えない場合がありますが、見えないだけで未作成と決めず、コマンドの終了状況と実行先を確認します。同じ場所で作成を繰り返す前に、既に環境があるかを調べましょう。

確認用スクリプトで場所を見えるようにする

親フォルダーvenv-lessonの直下へ、次のコードをcheck_env.pyという名前で保存します。.venvの中には入れません。このコードは環境を変更せず、Pythonの版・実行先・現在地と、packagingが導入されているかを表示します。ファイル名をpackaging.pyやsys.pyにすると、本来のモジュールと名前がぶつかる原因になるため、指定した別名を使ってください。

import importlib.metadata
import json
from pathlib import Path
import sys

try:
    package_version = importlib.metadata.version('packaging')
except importlib.metadata.PackageNotFoundError:
    package_version = None

print(json.dumps({
    'python_version': sys.version.split()[0],
    'executable': sys.executable,
    'prefix': sys.prefix,
    'base_prefix': sys.base_prefix,
    'in_venv': sys.prefix != sys.base_prefix,
    'cwd': str(Path.cwd()),
    'packaging': package_version,
}, ensure_ascii=False, indent=2))

sys.prefixは今動いている環境の場所、sys.base_prefixは土台になったPythonの場所です。通常のvenvでは二つが異なることで、仮想環境内の実行を判断できます。cwdは作業フォルダーです。例えばcwdがvenv-lessonでも、executableはproject-aの.venvを指す、という組み合わせがあり得ます。実行先と現在地は別の情報だと分かる出力になっています。

有効化せずにAとBを比較する

まずは直接指定を試します。親フォルダーを現在地とし、WindowsのPowerShellなら次のように実行します。空白を含む絶対パスを引用符で囲んで指定する場合は、PowerShellの呼び出し演算子&が必要になるなど、シェルの書き方にも注意してください。下の相対パス例には空白を含めていません。

.\project-a\.venv\Scripts\python.exe check_env.py
.\project-b\.venv\Scripts\python.exe check_env.py

macOS・Linuxでは次のパスを使います。新規作成時点の標準的な分離環境なら、AもBもin_venvがtrueで、packagingはnullです。実際の確認で別の値が出た場合は、既存環境を再利用していないか、作成時に外側のパッケージを共有する設定を選んでいないかを調べます。

./project-a/.venv/bin/python check_env.py
./project-b/.venv/bin/python check_env.py

Aのprefixにはproject-a/.venv、Bにはproject-b/.venvが含まれることを見ます。共通のbase_prefixが表示されても異常ではありません。同じPythonを土台に二つの環境を作ったからです。重要なのは、パッケージの置き場を示すprefixと、実際に呼んだexecutableが想定先を指すことです。

有効化と解除は今のターミナルに対して行う

毎回長いパスを書く代わりに、project-aへ移動して有効化する方法もあります。以下の表はproject-aを現在地とする場合の例です。使っているOSだけでなく、シェル名を合わせてください。PowerShellとコマンドプロンプトは、どちらもWindows上で使えますが、同じ有効化ファイルを同じ方法で呼ぶわけではありません。

※表は横にスクロールできます。

有効化後はpython ../check_env.pyを実行し、Aを指すことを確認します。作業を終えたらdeactivateで解除します。解除は仮想環境のフォルダーを削除する操作ではありません。再び使うときは同じ環境を有効化できます。ターミナルを閉じても環境フォルダーは残り、通常、新しく開いたターミナルには以前の有効化状態は引き継がれません。

PowerShellでスクリプト実行が拒否された場合、理由を確かめず実行ポリシーを緩めないでください。組織の制限が関係する場合は管理者に相談し、許可された範囲で環境内のpython.exeを直接指定する方法を使います。AからBへ切り替えるときも、まず解除してからBへ移動し、Bの有効化と確認を行うと、現在の状態を追いやすくなります。

python -m pipで追加先をそろえ、Aだけの依存関係を確かめる

pipだけで呼ばず、使うPythonを先に選ぶ

pipはパッケージを導入・確認するためのツールです。ターミナルでpipとだけ打つと、どのpipが見つかるかは検索順に依存します。Pythonを複数入れた端末では、プログラムを動かすPythonと、pipが対象にしているPythonがずれることがあります。「入れたはずなのにimportできない」の原因を減らすため、本記事では選んだPythonに続けて-m pipと書きます。

有効化したAでpython -m pip –versionを実行すると、pipの版だけでなく、どこから読み込まれたかが表示されます。そのパスにproject-aの.venvが含まれることを確認してください。python –versionだけでは、同じ版のPythonを使うAとBを区別できません。check_env.pyのexecutable・prefixと、pip –versionの場所を合わせて確認します。

外部パッケージを追加する前に、作成直後のpython -m pip listやpython -m pip freezeを見るのも役立ちます。ただし、二つの一覧は目的が異なります。listは導入済みパッケージの一覧、freezeは要求ファイルに使える形式での出力です。pipなど一部の基盤パッケージはfreezeの既定出力から省かれるため、何も表示されないからpipが壊れている、という判断はできません。

Aだけに固定版を追加する

Aを有効化し、実行先がAであることを確認した状態で、次を実行します。インターネットへ接続してPyPIからパッケージを取得する操作です。通信が許可されている環境で行い、組織が指定した配布元がある場合はその手順に従ってください。本番の依存関係を更新する練習ではないため、既存案件の環境では実行しません。

python -m pip --version
python -m pip install "packaging==25.0"
python -m pip show packaging
python -m pip check
python ../check_env.py
python -c "from packaging.version import Version; print(Version('1.10') > Version('1.9'))"

最後の行はバージョン表記を比較し、Trueが出ることを確認する小さな動作試験です。文字列の見た目の順序だけに頼らず、導入したパッケージの機能を実際に呼べたことを見ます。今回のLinux検証ではpackagingが25.0と表示され、この比較はTrue、pip checkは依存関係の不整合なしという結果になりました。

pip checkは、導入済みパッケージ間で宣言された依存関係に問題がないかを確認するコマンドです。自作プログラムの全機能や、パッケージの安全性まで保証するものではありません。導入成功の表示、依存関係の確認、自分の処理の動作確認はそれぞれ役割が違います。案件では小さなimportだけで終わらず、実際の入力を使ったテストも用意します。

解除してBでは見つからないことを確認する

Aでの確認を終えたらdeactivateを実行し、親フォルダーへ戻ってBのPythonを直接指定し、check_env.pyを実行します。ここでBのpackagingがnullなら、Aへの追加がBへそのまま反映されていないことを確認できます。Aに戻すと25.0が見つかり、Bでは見つからない、という往復ができれば、分離の理解が一歩進みます。

nullという表示は、この確認コードがPackageNotFoundErrorを受けて「導入版を取得できなかった」と記録した結果です。Bで実際にimport packagingと書いたプログラムを動かせば、通常はModuleNotFoundErrorになります。エラーを見たくないからBにも急いで追加するのではなく、今回は分離ができた証拠として扱いましょう。Bの仕事で必要になったときに、Bの依存関係として導入を判断します。

※表は横にスクロールできます。

この表は今回の新規venvを使った検証条件です。作成時に外側のsite-packagesを見せる設定を有効にした環境や、既存のパッケージがある環境では同じ初期状態になりません。特に–system-site-packagesは分離の条件を変えるため、今回の練習では指定しません。意図せず共有されていないかは、.venv内のpyvenv.cfgの設定と、実行先を照合して確かめます。

更新・削除より先に現在の記録を残す

不具合が出たときに、すぐ全パッケージを最新版にしたり、手当たり次第に削除したりすると、元の状態との比較が難しくなります。まずpythonの版、pipの版、freezeの結果、再現する入力、エラー全文を保存します。更新が必要だと判断したら、新しい練習環境に同じ条件を再現し、一つずつ変更して試すと影響を追いやすくなります。

パッケージ名はPyPIのpackaging 25.0のような正しい配布ページで確認します。似たつづりの別パッケージや、不明なサイトから案内されたインストール命令をそのまま使わないでください。認証トークン付きのURLをターミナルや記事へ貼ることも避けます。学習用の公開パッケージだけで、分離と再現の基本は練習できます。

依存関係を記録し、別名の環境で再作成を検算する

freezeは現在の一覧であり、完全な環境保存ではない

Aが動いたら、その場で依存関係を記録します。python -m pip freezeは導入されたパッケージの版を要求ファイル向けに出力します。ただし、これはOS、CPU、Python本体、システムライブラリ、環境変数、入力データまで丸ごと保存するものではありません。pip公式もfreezeをインストール済みの報告と説明しており、依存関係を解決したロックファイルの計算と同一視しないことが大切です。

今回のようにパッケージが一つで依存も単純な小例なら、packaging==25.0という記録を読み直すことで、元の条件を追いやすくなります。大きな案件では直接必要なものと、依存先として追加されたものを区別して管理する場合もあります。その際はチームのpyproject.tomlやロックファイルの運用を優先し、既に管理されているファイルをfreezeの結果で上書きしないでください。

既存ファイルを上書きしない保存用コード

シェルの出力リダイレクトは便利ですが、保存先が既にあると内容を置き換える書き方があります。初心者の練習では、存在するファイルに気付けるよう、次のコードをsave_requirements.pyとして親フォルダーへ保存します。Aを有効化し、project-aを現在地としてpython ../save_requirements.pyで実行してください。

from pathlib import Path
import subprocess
import sys

if sys.prefix == sys.base_prefix:
    raise RuntimeError('仮想環境のPythonで実行してください')

result = subprocess.run(
    [sys.executable, '-m', 'pip', 'freeze'],
    check=True, capture_output=True, text=True, encoding='utf-8'
)
target = Path('requirements-new.txt')
with target.open('x', encoding='utf-8', newline='\n') as file:
    file.write(result.stdout)
print(target.resolve())

このコードは、今動いているPythonからpip freezeを呼び、project-a内へrequirements-new.txtを新規作成します。openのxモードを使うため、同じ名前のファイルが既にあればFileExistsErrorで止まります。これは記録を失わないための動作です。やり直す場合は既存ファイルの内容を確認し、新しい記録用の名前をコード側で選ぶなど、元の記録を残したまま進めます。

subprocessに渡すPythonとしてsys.executableを使っているので、別のpipを拾う誤りを減らせます。仮想環境でない場合も冒頭で止まるようにしています。ただし「仮想環境なら何でも正しい」わけではありません。Aで記録するつもりなのにBを選んでいた、という誤りは、実行前のcheck_env.pyで見分ける必要があります。

今回の実行では、requirements-new.txtの内容はpackaging==25.0の1行でした。保存コードをもう一度実行するとFileExistsErrorになり、最初の記録が維持されることも確認しています。出力内容を開いて、予想外の大量のパッケージや、ローカルパス、認証情報の付いたURLが混じっていないかを確認してから、人へ渡す準備をします。

元のAを残したまま、新しいAを作る

再現試験では、動いているAを削除せず、親フォルダーにproject-a-rebuildという別名のフォルダーを作ります。新しい場所にvenvを作り、Aで記録した要求ファイルを指定して導入します。まずAの有効化を解除し、venv-lessonへ戻ります。次はmacOS・Linuxでの例です。project-a-rebuildが既にある場合は別名を選び、既存内容に重ねないでください。

mkdir project-a-rebuild
python3 -m venv project-a-rebuild/.venv
./project-a-rebuild/.venv/bin/python -m pip install -r project-a/requirements-new.txt
./project-a-rebuild/.venv/bin/python -m pip check
./project-a-rebuild/.venv/bin/python check_env.py
./project-a-rebuild/.venv/bin/python -c "from packaging.version import Version; print(Version('1.10') > Version('1.9'))"

Windowsでは作成に確認済みのpy -m venvを使い、実行先を.\project-a-rebuild\.venv\Scripts\python.exeに置き換えます。読み込む要求ファイルはproject-a\requirements-new.txtです。Aと再構築先で同じ版が出ることに加え、prefixは別の場所になっていることを確認します。同じAを二度調べただけでは再構築の検証にならないためです。

Linuxでの実行では、再構築先にpackaging 25.0が導入され、pip checkとバージョン比較がAと同じ結果になりました。Bに何も追加していないことも維持されています。requirementsからの導入には配布元への接続が必要になる場合があり、将来も必ず同じファイルが取得できることや、異なるOSで全パッケージが動くことまではこの試験では確認していません。

引き継ぎには手順と検算結果を付ける

引き継ぎ資料では、Python 3.12系といった大きな区分だけでなく、実際に試した3.12.14という値、OS、シェル、pipの版、使用した要求ファイル名、作成と実行の順番を残します。結果としてAと再構築先のpackagingが25.0、比較結果がTrue、Bでは未導入だったことを書けば、受け取り側が確かめる目印になります。

フォルダー一式を共有するときは、.venvは通常除外します。Gitを使う場合も、Pythonの版による自動生成の違いに頼らず、プロジェクト側の除外設定で.venv/が扱われるか確認しましょう。requirementsやREADMEに個人PCの不要な絶対パス、トークン、会社の内部配布先などを残さないことも大切です。作品の説明や動作条件を整える観点は、プログラミングのポートフォリオの作り方でも扱っています。

動かないときの切り分けと、安全に続ける環境管理

エラーは「作成・選択・導入・実行」のどこかを分ける

最初に止まった操作を確認します。venv作成自体が失敗したのか、有効化が拒否されたのか、pipで取得できなかったのか、導入後のimportが失敗したのかで調べる場所が変わります。最後のエラー行だけを見て別のコマンドを追加すると、状況が混ざりやすくなります。実行した行、現在地、Pythonの実行先、エラー全文を同じ記録にまとめてください。

※表は横にスクロールできます。

インターネット上には、管理者権限でやり直す、証明書の確認を飛ばす、OS管理のPythonに強制導入する、といった対処が見つかることがあります。しかし、原因を特定せずに権限や保護を外すと、環境の問題を広げかねません。特に仕事用端末では、組織の管理ルールに沿って相談し、今回の小さな練習のために全体設定を変えないでください。

エディターとターミナルが別のPythonを選ぶ場合

ターミナルでは動くのに、エディターの実行ボタンではModuleNotFoundErrorになる場合、エディター側が別のインタープリターを使っている可能性があります。check_env.pyを両方から実行し、executableとprefixを比較すると切り分けられます。同じファイルを開いていることと、同じPythonで動いていることは別です。

エディターやNotebookの設定画面は製品・版によって異なるため、本記事では一律のクリック順を示しません。対象製品の公式手順でプロジェクト用Pythonまたはカーネルを選び、選択後に同じ確認コードを実行してください。venvを作り直した場合、古い実行パスがエディターに残っていないかも見ます。見た目の環境名が同じでも、実ファイルの場所は確認できます。

また、Pythonは実行場所にある自作ファイルから同名モジュールを読み込むことがあります。packaging.pyなどの名前を付けたファイルがあると、venvが正しくても予想外のものをimportする場合があります。導入版の表示だけで判断せず、疑わしいときは対象モジュールの__file__なども確認し、自分のファイル名との衝突を調べます。原因を見ずに追加インストールを繰り返さないことが大切です。

環境の掃除は再現できることを確かめてから

使わなくなった環境は残し続ける必要はありませんが、削除を急ぐ前に、.venvの中へ自作コードやデータを置いていないか、必要な依存関係の記録があるか、別名の環境で再現できたかを確認します。この記事には強制削除のコマンドを載せていません。削除対象を見誤ると成果物まで失うため、手元の通常のファイル管理操作と復元方法を理解してから扱ってください。

venvの–clearは指定先の内容を消して作成するオプションなので、作成に失敗したときの万能なやり直し命令として使いません。動くAを残してA-rebuildを作る進め方なら、途中で失敗しても比較対象が残ります。新しい環境が正しく動くと確認した後に、必要な記録を保管し、不要な環境の整理を判断できます。

学習用と納品用で求める再現性を変える

個人の小さな練習なら、今回の二環境と固定版一つで分離の仕組みを理解できます。仕事で複数人が使うツールなら、Pythonの対応版、OS、依存関係の管理方法、テスト用データ、期待出力、更新時の確認項目までそろえる必要があります。環境が作れたことと、納品先で安心して使えることを同じ完了条件にしないようにしましょう。

自分で切り分けられない場合は、質問に「実行コマンド」「OS・Pythonの版」「executableとprefix」「エラーの出る最小コード」を添えると、相手が状況を再現しやすくなります。共有前に個人名を含む不要なパス、社内URL、秘密情報を取り除きます。独学で同じ環境問題に何度も止まるなら、質問対応や開発環境の支援内容も学習サービスを選ぶ基準になります。必要な場合は副業向けプログラミングスクールの比較を参考にし、まず自分に必要な支援を整理してください。

今回実行したのは、Linux上でのA・B・再構築先のvenv作成、Aだけへのpackaging 25.0導入、環境確認、bashの有効化と解除、上書きを拒否する記録、要求ファイルからの再導入と検算です。Windows・macOS、会社PCの制限、異なるPython版や大規模な依存関係では別途確認が必要です。この範囲を記録しておくと、成功した小例を必要以上に一般化せずに次の作業へ進めます。

作成した場所、実行しているPython、追加する先、再現に残す記録。この四つを毎回確認できれば、仮想環境は単なるおまじないから、案件ごとの条件を管理する道具になります。まずはAだけで動く小例と、Bでは未導入という差を自分の画面で確認し、別名の環境で同じ結果を出すところまで終えてみてください。

仕様の根拠は、Python 3.12のvenv公式資料、PyPAのpip・venvガイド、pip freeze、pip checkです。参照先の表示版が更新される場合もあるため、本記事の確認日と実行版を分けて読んでください。