Macで始めるPython venv：環境を汚さない仮想環境入門

Pythonでパッケージを試すとき、Mac全体へ直接インストールすると、別の授業や研究で使うバージョンと衝突することがあります。そこで役立つのが、プロジェクトごとに独立した環境を作るvenvです。

この記事では「Python venv Mac」をテーマに、練習用フォルダの作成から仮想環境の終了、削除、再作成までを順番に試します。作業は専用フォルダ内だけで行い、既存プロジェクトやMacのシステム環境には触れません。

この記事で分かること

• MacでPythonの仮想環境を作成し、有効化する方法
• 仮想環境へパッケージを入れ、導入状態を保存する方法
• 作業終了、再開、削除、エラー確認までの安全な流れ

Python venvをMacで使う理由

venvは、Pythonに標準で用意されている仮想環境作成機能です。仮想環境を作ると、そのフォルダ専用のPython実行環境とパッケージ保存場所が用意されます。たとえば、授業Aでは新しいライブラリ、研究Bでは古いバージョンが必要でも、別々の仮想環境に分ければ衝突を避けやすくなります。

大切なのは、仮想環境がMacそのものを仮想化する仕組みではない点です。DockerのようにOSを含む環境を作るのではなく、主にPython本体の参照先とパッケージの保存先をプロジェクト単位で分けます。そのため動作が軽く、Pythonだけで完結する小規模な学習、データ処理、スクレイピング、Bot開発などに向いています。

Python公式ドキュメントでも、アプリケーションごとに異なるライブラリやバージョンが必要になる問題への解決策として、仮想環境が説明されています。詳しい仕様はPython公式のvenvドキュメントで確認できます。

仮想環境ありと直接インストールの違い

仮想環境を使わずにpipを実行すると、使っているPythonの設定によっては、ユーザー全体やシステムに近い場所へパッケージが入ります。学習を始めた直後は便利に見えますが、複数プロジェクトを扱うようになると「どの作業のために入れたのか」が分かりにくくなります。

比較項目	venvを使う	直接インストールする
パッケージの保存先	プロジェクト専用	Mac内の共通環境になりやすい
バージョンの分離	プロジェクトごとに可能	衝突する可能性がある
作り直し	.venvを削除して再作成	影響範囲の確認が必要
Gitでの扱い	設定ファイルだけ共有しやすい	環境を再現しにくい
初心者の確認	作業範囲が見えやすい	導入先が分かりにくい場合がある

Pythonライブラリだけで完結する作業なら、まずvenvを選ぶと構成を小さく保てます。一方、PHP、SQL、複数サービス、厳密なOS依存関係まで含む課題では、Dockerの方が適している場合があります。今回はPythonだけを扱うため、軽量なvenvを使います。

作業前に確認すること

この記事ではmacOSのターミナルとzshを使います。まずターミナルを開き、Python 3を実行できるか確認します。

python3 --version

Python 3.x.xのように表示されれば、次へ進めます。command not foundと表示された場合は、まだPython 3を利用できる状態ではありません。その場合は作業を進めず、授業やプロジェクトで指定された導入方法を確認してください。既存環境がある状態で、別のPythonを安易に追加すると、実行先が複数になって混乱することがあります。

続いて、現在の場所を確認します。

pwd

このあと作る練習用フォルダ以外は削除しません。既存の授業フォルダや開発フォルダ内で試したくない場合は、ホームディレクトリへ移動してから始めます。

cd ~

最初に試す手順

今回の作業全体は次の順番です。先に流れを確認しておくと、現在どの環境を操作しているか見失いにくくなります。

☐ `python3 –version`でPython 3を確認する

☐ 練習用フォルダを作成する

☐ `.venv`という仮想環境を作成する

☐ 仮想環境を有効化する

☐ Pythonとpipの参照先を確認する

☐ 練習用パッケージをインストールする

☐ `requirements.txt`へ導入状態を保存する

☐ `deactivate`で仮想環境を終了する

☐ 仮想環境を再度有効化する

☐ 必要に応じて`.venv`を削除し、再作成する

練習用フォルダを作成する

ホームディレクトリの下に、今回だけ使うpython-venv-practiceフォルダを作成します。

mkdir -p ~/python-venv-practice
cd ~/python-venv-practice

移動できたか確認します。

pwd

表示の末尾がpython-venv-practiceになっていれば準備完了です。このフォルダを作業範囲として扱います。今後、削除コマンドを使う場合も、必ずpwdでこの場所にいることを確認してください。

.venvを作成する

練習用フォルダの中で、次のコマンドを実行します。

python3 -m venv .venv

-m venvは、現在指定したPython 3で標準モジュールのvenvを実行する指定です。最後の.venvは作成するフォルダ名です。先頭がドットの名前はmacOSで通常は隠しフォルダとして扱われるため、プロジェクトのファイル一覧が散らかりにくくなります。

作成結果は次のコマンドで確認できます。

ls -la

一覧に.venvがあれば作成できています。仮想環境の中にはPython実行ファイルや有効化スクリプト、パッケージ保存場所などが入ります。これらは自動生成物なので、通常は中身を手作業で編集しません。

仮想環境を有効化する

macOSやLinuxなどのPOSIX環境では、次のコマンドで仮想環境を有効化します。

source .venv/bin/activate

成功すると、ターミナルの入力行付近に(.venv)と表示されることがあります。表示方法はターミナル設定によって異なるため、名前が見えない場合は実行先を確認します。

which python
which pip

どちらもpython-venv-practice/.venv/bin/を含むパスなら、仮想環境側のコマンドが選ばれています。有効化は、シェルのPATH先頭へ仮想環境のbinディレクトリを加える操作です。Mac全体のPythonを削除したり、置き換えたりする操作ではありません。

pipを確認してパッケージを入れる

仮想環境を有効化したまま、pipの参照先を確認します。

python -m pip --version

ここでは単独のpipよりもpython -m pipを使います。実行中のPythonと同じ環境にあるpipを明示しやすくなるためです。表示されたパスに.venvが含まれていることを確認してください。

練習として、HTTP通信でよく使われるrequestsを仮想環境へ入れます。

python -m pip install requests

インストール後、導入済みパッケージを確認します。

python -m pip list

requestsと、その動作に必要な関連パッケージが一覧に表示されます。これらは今回作った.venvの中へ保存されるため、別の仮想環境には自動で入りません。

Pythonから動作を確認する

インストールしたrequestsを読み込めるか確認します。外部サイトへ通信しなくても、バージョン表示だけで導入状態を試せます。

python -c "import requests; print(requests.__version__)"

バージョン番号が表示されれば成功です。ModuleNotFoundErrorが出た場合は、仮想環境が有効か、別のPythonを実行していないかを確認します。

which python
python -m pip show requests

which pythonとpython -m pip show requestsの両方を確認すると、実行中のPythonとパッケージの導入先を切り分けられます。

requirements.txtへ導入状態を保存する

仮想環境は、そのフォルダを別のMacへコピーして使い回すものではありません。代わりに、必要なパッケージ情報をテキストへ保存し、新しい環境で入れ直せるようにします。

python -m pip freeze > requirements.txt

内容を確認します。

cat requirements.txt

requests==...のように、現在導入されているパッケージとバージョンが表示されます。公式pipドキュメントでは、pip freezeは現在の導入状態をrequirements形式で出力する機能です。ただし、依存関係を計算した厳密なロックファイルではありません。現在の環境を記録する簡単な方法として使います。詳しくはpip freeze公式リファレンスを確認してください。

仮想環境を終了する

作業が終わったら、次のコマンドで仮想環境を終了します。

deactivate

ターミナルに表示されていた(.venv)が消え、which pythonの結果も仮想環境外の参照先へ戻ります。deactivateは.venvフォルダを削除するコマンドではありません。現在のシェルで行った有効化を解除するだけです。

ターミナルのウィンドウやタブを閉じた場合も、そのシェルでの有効化状態は終了します。次回はプロジェクトフォルダへ移動し、もう一度有効化します。

次回の作業を再開する

新しいターミナルを開いたあと、次の2つを実行します。

cd ~/python-venv-practice
source .venv/bin/activate

その後、参照先を確認します。

which python
python -m pip list

前回導入したrequestsが表示されれば、同じ仮想環境を再利用できています。仮想環境はターミナルを開くたびに自動で有効になるわけではありません。プロジェクトへ移動してから有効化する習慣を付けると、別の作業環境を誤って操作しにくくなります。

Gitで管理するときの考え方

通常、.venvフォルダはGitへコミットしません。自動生成された大量のファイルが含まれ、作成した環境やパスに依存するためです。Gitで管理するプロジェクトでは、プロジェクト直下の.gitignoreへ次の行を追加します。

.venv/

共有するのは、Pythonコード、README、requirements.txtなどの再作成に必要なファイルです。共同作業者は自分の環境で.venvを作り、requirementsファイルからパッケージを導入します。

なお、Python 3.13のvenvには、作成時にGit用のignoreファイルを生成する仕組みがありますが、Pythonのバージョンや既存運用によって挙動が異なります。初心者はプロジェクトの.gitignoreを自分で確認し、.venv/が除外されていることを確かめる方法が分かりやすいです。

仮想環境を削除して作り直す

仮想環境内のパッケージ構成が分からなくなった場合は、中身を一つずつ修復するより、.venvを作り直す方が簡単なことがあります。まず練習用フォルダへ移動し、現在地を確認します。

cd ~/python-venv-practice
pwd

仮想環境が有効なら終了します。

deactivate

.venvだけを削除します。

rm -rf .venv

rm -rfは確認なしで削除する強いコマンドです。必ずpwdと削除対象の名前を確認し、変数やワイルドカードを使わず、練習用フォルダ内の.venvだけを指定してください。

続いて、新しい仮想環境を作り、保存した一覧からパッケージを戻します。

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt

この流れにより、壊れた環境を抱え続けず、再現可能な状態へ戻せます。

よくあるエラーと確認方法

python3が見つからない

python3 --versionでcommand not foundが出る場合、この記事の手順だけでは進められません。授業、研究室、既存プロジェクトで指定されているPythonの導入方法を確認してください。既にpyenvやHomebrewを使っている場合は、別方式を重ねて入れる前に、現在の設定を確認する必要があります。

activateファイルが見つからない

source .venv/bin/activateでエラーになる場合は、現在地が違うか、.venvがまだ作成されていない可能性があります。

pwd
ls -la

練習用フォルダに移動し、一覧に.venvがあるか確認します。

pipで入れたのにimportできない

パッケージを入れたPythonと、コードを実行したPythonが異なる可能性があります。

which python
python -m pip --version
python -m pip list

出力パスに同じ.venvが含まれているか確認します。

仮想環境名が表示されない

ターミナルのテーマや設定によっては、仮想環境を有効化しても(.venv)が表示されないことがあります。見た目だけで判断せず、which pythonで実行先を確認してください。

deactivateが使えない

deactivate: command not foundのように表示される場合、そのシェルでは仮想環境が有効になっていない可能性があります。別のタブで有効化した状態は引き継がれません。現在のタブでwhich pythonを確認してください。

初心者向け用語表

専門用語	意味	初心者向けの言い換え
venv	Pythonの仮想環境を作る標準機能	プロジェクト専用のPython置き場
仮想環境	Pythonとパッケージを分離した環境	ほかの課題と混ざらない作業箱
pip	Pythonパッケージの導入ツール	必要な追加部品を入れる道具
activate	仮想環境を現在のシェルで使えるようにする処理	専用環境へ切り替える操作
deactivate	仮想環境の有効化を解除するコマンド	専用環境から戻る操作
PATH	コマンドを探す順番を示す設定	どのPythonを先に使うかの順番
requirements.txt	導入するパッケージを記録するファイル	環境を作り直すための部品表

よくある質問

Q1. フォルダ名は必ず.venvですか？

いいえ。tutorial-envやvenvなど別の名前も使えます。ただし、プロジェクト直下の.venvは用途が分かりやすく、多くのエディタでも認識されやすい名前です。チームや授業で命名規則がある場合は、その指定を優先してください。

Q2. 仮想環境はプロジェクトごとに必要ですか？

基本的には、依存関係を分けたい単位ごとに作ります。小さな練習を一つの環境へまとめることもできますが、目的の異なる課題は分けた方が、削除や再作成をしやすくなります。

Q3. activateしないとPythonを実行できませんか？

有効化は必須ではなく、.venv/bin/pythonのように仮想環境内の実行ファイルを直接指定する方法もあります。ただし初心者の手作業では、有効化してからwhich pythonで確認する流れが分かりやすいです。

Q4. .venvを別のMacへコピーできますか？

おすすめしません。仮想環境には作成場所に依存する情報が含まれるため、移動やコピーを前提にしない方が安全です。コードとrequirementsファイルを共有し、移動先で新しく作成してください。

Q5. requirements.txtがあれば完全に同じ環境になりますか？

必ずしも完全一致とは限りません。pip freezeは現在導入されている状態を一覧にしますが、OS、Pythonのバージョン、利用できる配布物などの違いは別に考える必要があります。授業やチームではPythonのバージョンもREADMEへ記録すると再現しやすくなります。

Q6. Dockerとvenvはどちらを使うべきですか？

Pythonライブラリだけを分離したい場合はvenvが軽くて簡単です。データベース、PHP、特定OSのパッケージなども含めて環境を固定したい場合はDockerが向いています。必要な分離範囲で選びます。

Q7. 仮想環境を消すとPythonコードも消えますか？

.venvだけを削除すれば、通常はプロジェクト直下に置いたPythonコードやrequirements.txtは残ります。ただし、削除コマンドの対象を間違えると別のファイルも消えるため、実行前にpwdと対象名を必ず確認してください。

まとめ

MacでPythonを学ぶときは、プロジェクト専用フォルダを作り、その中に.venvを用意すると環境を整理しやすくなります。基本の流れは、python3 -m venv .venvで作成し、source .venv/bin/activateで有効化し、作業後にdeactivateで終了する形です。

パッケージはpython -m pipで操作し、必要に応じてpython -m pip freeze > requirements.txtで現在の導入状態を記録します。環境が混乱した場合は、コードやrequirementsファイルを残したまま.venvだけを削除し、再作成できます。

最初は練習用フォルダで一連の操作を試し、which pythonで実行先を確認する習慣を付けてください。環境を小さく分離し、いつでも作り直せる状態にしておくことが、Python開発を安定させる基本です。