【Mac】Python venv 完全攻略ガイド｜python3コマンドとの関係からboto3導入まで

はじめに

Macで Python を使い始めると、ほぼ全員が一度はこのエラーに出会います。

error: externally-managed-environment

pip install boto3 と打っただけなのに弾かれる。これは故障ではなく、「venv を使いなさい」という Python からのメッセージです。

この記事では、

• なぜ Mac で venv（仮想環境）が必須なのか
• python / python3 / py コマンドの違い（混乱しやすいポイント）
• venv の作成・有効化・削除の正しい手順
• 実例として boto3（AWS SDK）をクリーンに導入する流れ
• requirements.txt と .gitignore による再現性の確保
  を、「とりあえず動く」ではなく「なぜそうするか」が分かる形で順に解説します。コマンドは全て macOS（Apple Silicon / Intel 共通）を前提にしています。

対象読者：Python を触り始めた人 / 他人の手順をコピペしてきたが仕組みが分からない人 / Mac で pip install が通らず困っている人

結論：先に全体像

細かい説明の前に、最終的に打つコマンドを示します。これが「正解の型」です。

# 1. プロジェクト用フォルダを作る
mkdir my-project && cd my-project
 
# 2. その場に仮想環境を作る
python3 -m venv .venv
 
# 3. 有効化する
source .venv/bin/activate
 
# 4. この中なら pip が自由に使える
pip install boto3
 
# 5. 作業が終わったら無効化
deactivate

ポイントは 「プロジェクトごとに .venv という箱を作り、その中だけで pip する」 こと。以降、この各ステップが何をしているのかを掘り下げます。

1. Macの「Python事情」を整理する

システムにある Python は触らない

最近の macOS には Python 本体は同梱されておらず、初めて python3 を叩いたタイミングで「Command Line Tools をインストールしますか？」と聞かれます。これで入るのが、いわゆるシステム Pythonです。

このシステム Python は OS や各種ツールが内部的に使っているもので、ここに自分のライブラリを直接インストールするのは禁物です。バージョンを上げたり依存を入れ替えたりすると、思わぬところで OS 側の処理が壊れる可能性があります。

実際、Homebrew や python.org で入れた新しい Python では、保護のために素の pip install がブロックされます。これが冒頭の externally-managed-environment エラーの正体です（仕組みとしては PEP 668 という規約）。

つまりエラーは「壊れている」のではなく「グローバルを汚すな、仮想環境を使え」という設計通りの動作です。

python / python3 / py の違い

ここが初心者の最大の混乱ポイントです。表で整理します。

コマンド	Mac での扱い	補足
python3	これを使う	Mac で標準的に存在する呼び名
python	存在しないことが多い	古い習慣。command not found になりがち
py	Macには存在しない	Windows専用の「Python Launcher」だから

特に注意したいのが py です。ネット記事で py -m venv ... という書き方を見かけることがありますが、py は Windows 限定のランチャーであり、Mac には基本的に入っていません。Mac でその通りに打つと command not found: py となります。

Macでは py を python3 に読み替える ——これだけ覚えておけば、Windows向け記事もそのまま流用できます。

# Windowsの記事に py と書いてあったら…
py -m venv .venv      # ❌ Macでは動かない
 
# Macではこう
python3 -m venv .venv  # ✅

同様に pip と pip3 も、仮想環境を使えば気にする必要がなくなります（後述）。

2. venvとは何か：「箱」のイメージで理解する

venv（virtual environment＝仮想環境）は、プロジェクト専用の独立した Python 環境です。

イメージとしては、プロジェクトごとにライブラリ専用の箱を用意する感じです。

• プロジェクトA：boto3 の最新版が必要
• プロジェクトB：古い boto3 で動かす必要がある
  これをグローバルに直接入れると、A と B が同じライブラリを奪い合って共倒れします（依存関係の地獄）。venv なら、それぞれの箱に別バージョンを入れて完全に分離できるため、衝突しません。

しかも箱はフォルダごと消せば跡形もなく消えるので、環境を壊しても rm -rf .venv でやり直せます。システムは一切汚れません。

3. venvを作る・有効化する

作成

プロジェクトフォルダの中で実行します。

cd my-project
python3 -m venv .venv

• python3 -m venv … 「venvモジュールを実行せよ」という意味
• .venv … 作られる箱（フォルダ）の名前。.venv か venv が慣習
  .venv（先頭ドット）にしておくと隠しフォルダ扱いになり、エディタの一覧で目立たないため人気です。VS Codeも .venv を自動検出してくれます。

有効化（activate）

source .venv/bin/activate

成功すると、プロンプトの先頭に環境名が付きます。

(.venv) ~/my-project $

この (.venv) が出ている間は、python も pip も自動的に箱の中のものを指します。つまり：

• python と打つだけで箱の中の Python が動く（python3 と打たなくてOK）
• pip install がエラーなく通る（箱の中なので保護対象外）
  pip / pip3 問題も、python3 / python 問題も、activate した瞬間に解決するわけです。

今どこを指しているか確認する

不安なときはこれで確認できます。

which python
# → /Users/you/my-project/.venv/bin/python と出れば成功

パスに .venv が含まれていれば、ちゃんと箱の中を見ています。

4. 実践：boto3を入れる

AWS を Python から操作する SDK が boto3 です。venv の有効化後にインストールします。

# (.venv) が付いている状態で
pip install boto3

externally-managed-environment は出ません。箱の中だからです。

入ったか確認

pip show boto3      # バージョンやインストール先を表示
python -c "import boto3; print(boto3.__version__)"

boto3は「鍵」が別途必要

boto3 はインストールしただけでは AWS にアクセスできません。認証情報（クレデンシャル）が必要です。AWS CLI を入れて設定するのが一般的です。

aws configure

対話形式でアクセスキー等を入力すると ~/.aws/credentials に保存され、boto3 が自動で読み込みます。

import boto3
 
# S3のバケット一覧を取得する最小例
s3 = boto3.client("s3")
for bucket in s3.list_buckets()["Buckets"]:
    print(bucket["Name"])

セキュリティ注意：アクセスキーをコード内に直書きしたり Git にコミットしたりしないこと。~/.aws/credentials や環境変数、IAMロールで管理します。

5. チームと未来の自分のために：再現性を確保する

requirements.txt で依存を固定

今の箱に入っているライブラリ一覧を書き出します。

pip freeze > requirements.txt

中身はこうなります。

boto3==1.x.x
botocore==1.x.x
...

別の Mac や同僚は、これ一つで同じ環境を復元できます。

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

.venvは絶対にGitに入れない

.venv フォルダは数千ファイル・数百MBになり、しかもマシン依存です。コミットしてはいけません。.gitignore に必ず追加します。

# .gitignore
.venv/

「コードと requirements.txt だけを共有し、.venv 自体は各自で作り直す」——これが鉄則です。箱そのものではなく「箱の設計図」を共有するイメージです。

6. よくあるトラブルと対処

症状	原因	対処
command not found: py	py はWindows専用	python3 に置き換える
externally-managed-environment	venvの外で pip install した	source .venv/bin/activate してから実行
command not found: python	Macに python（3なし）は無い	python3 を使う。activate後は python でOK
activateしたのに反映されない	別ターミナルを開いた	ターミナルごとに activate が必要
pip install が古い場所に入る	activateし忘れ	which python でパスを確認
環境を作り直したい	依存が壊れた	rm -rf .venv して再作成

最後の「消してやり直す」が気軽にできるのが venv の最大の利点です。グローバルだとこうはいきません。

まとめ

• Mac のシステム Python は触らない。pip がブロックされるのは仕様（PEP 668）
• py は Windows専用。Macでは python3 に読み替える
• プロジェクトごとに python3 -m venv .venv で箱を作る
• source .venv/bin/activate で有効化すれば、python / pip のコマンド問題もエラーも一気に解決
• boto3 は箱の中で pip install。さらに aws configure で認証情報を別途設定
• 共有するのは requirements.txt だけ。.venv は .gitignore へ
  「グローバルに入れず、プロジェクト単位で箱を分ける」——この一点を体に入れてしまえば、Python の環境周りで悩むことはほぼなくなります。