MacでPython環境を壊さないためにvenvとpipxを使い分ける

タイトル：MacでPython環境を壊さないためにvenvとpipxを使い分ける

はじめに

Mac で Python を使っていると、最初は pip install だけで進められます。
ただ、少しずつ触るツールやプロジェクトが増えてくると、次のような状態になりがちです。

• どの Python にライブラリを入れたのか分からない
• 以前動いていたプロジェクトが急に動かなくなる
• CLI ツールを入れたらプロジェクト側の依存と混ざる
• sudo pip install で何とかしようとして余計に怖くなる
• Homebrew、システム由来の Python、仮想環境の区別が曖昧になる

この記事では、Mac で Python 環境を壊しにくくするために、venv と pipx をどう使い分けるかを整理します。
細かいバージョン管理ツールの比較ではなく、日常的に迷わないための運用メモです。

対象読者

• Mac で Python を使い始めた人
• pip install の入れ先が分からなくなりやすい人
• Python 製 CLI ツールとプロジェクト依存を分けたい人
• チーム向けにシンプルな環境構築ルールを残したい人

結論

まずは次の使い分けにすると、かなり整理しやすくなります。

用途	使うもの	例
プロジェクトごとのライブラリ管理	venv	Django、Flask、FastAPI、データ分析スクリプト
Python 製 CLI ツールの導入	pipx	black、ruff、httpie、poetry
Python 本体の複数バージョン管理	pyenv など	Python 3.10 と 3.12 を切り替えたい場合

この記事で特に言いたいのは、次の 2 点です。

1. アプリやスクリプトの依存ライブラリは、プロジェクト内の venv に閉じ込める
2. コマンドとして使う Python 製ツールは、pipx で隔離して入れる

これだけでも、グローバル環境に何でも入れてしまう事故をかなり減らせます。

なぜグローバルな pip install を避けたいのか

Python では、ライブラリのインストール先が複数あります。

• macOS や Xcode Command Line Tools に由来する Python
• Homebrew で入れた Python
• pyenv で入れた Python
• プロジェクトごとの仮想環境
• ユーザー領域の site-packages

慣れていない段階で pip install だけを実行すると、「今どの Python に対して入れているのか」が見えにくくなります。

確認するには、最低限このあたりを見ます。

which python3
python3 --version
python3 -m pip --version
python3 -m pip list

ポイントは、pip 単体ではなく python3 -m pip の形で実行することです。
この形にすると、「この Python に対して pip を実行している」という対応関係が分かりやすくなります。

ただし、確認できることと、環境が混ざらないことは別です。
プロジェクトごとの依存は、最初から仮想環境に分けておく方が安全です。

venv はプロジェクトごとの作業場

venv は Python 標準の仮想環境作成機能です。
プロジェクトごとにライブラリを閉じ込めるために使います。

例として、作業ディレクトリに .venv を作る場合は次のようにします。

mkdir sample-python-app
cd sample-python-app

python3 -m venv .venv
source .venv/bin/activate

python -m pip install --upgrade pip
python -m pip install requests
python -m pip freeze > requirements.txt

有効化できているかは、次のコマンドで確認できます。

which python
python -m pip --version

.venv 配下の Python や pip が表示されれば、そのプロジェクトの仮想環境を使えています。

作業を終えるときは、次のコマンドで抜けます。

deactivate

.venv は Git に含めない

.venv は各自の PC 上で再作成するものなので、Git には含めません。

.gitignore には次のように書いておきます。

.venv/
__pycache__/
*.pyc

共有するのは、仮想環境そのものではなく依存関係の定義です。

シンプルなプロジェクトなら requirements.txt、もう少し整えるなら pyproject.toml を使うとよいです。

pipx はPython製CLIツールの置き場

venv はプロジェクトごとの作業場として便利ですが、CLI ツールの導入に使うと少し面倒です。

たとえば black や ruff のようなツールをグローバルコマンドとして使いたい場合、各プロジェクトの .venv に毎回入れるのか、どこか共通の Python に入れるのかで迷います。

この用途には pipx が向いています。

pipx は、Python 製のコマンドラインツールをツールごとの隔離環境に入れ、コマンドだけを使いやすい場所に出してくれます。

Homebrew を使っている場合は、次のように導入できます。

brew install pipx
pipx ensurepath

一度ターミナルを開き直してから、CLI ツールを入れます。

pipx install black
pipx install ruff
pipx install httpie

インストール済みツールは次で確認できます。

pipx list

削除も簡単です。

pipx uninstall black

pipx に向いているもの

pipx に向いているのは、「ライブラリとして import するもの」ではなく「コマンドとして実行するもの」です。

向いている例:

• black
• ruff
• httpie
• poetry
• cookiecutter

向いていない例:

• requests
• pandas
• numpy
• django
• fastapi

requests や pandas は、プロジェクトのコードから import して使うライブラリです。
この場合は pipx ではなく、そのプロジェクトの venv に入れます。

よくある使い分け

Django や FastAPI のアプリを作る

プロジェクトの .venv に入れます。

mkdir my-api
cd my-api

python3 -m venv .venv
source .venv/bin/activate

python -m pip install fastapi uvicorn
python -m pip freeze > requirements.txt

このプロジェクトでしか使わない依存は、プロジェクト内に閉じ込めます。

コードフォーマッターを手元のコマンドとして使う

個人の作業環境に CLI として入れたいなら pipx を使います。

pipx install black
black --version

ただし、チーム開発でバージョンを固定したい場合は、プロジェクト側の依存として管理した方がよいこともあります。

python -m pip install black
python -m pip freeze > requirements-dev.txt

個人用の便利ツールなら pipx、チームで同じ結果を保証したいツールならプロジェクト依存、という考え方です。

Poetry などのプロジェクト管理ツールを入れる

Poetry のような「プロジェクトを管理するためのCLI」は、pipx で入れると分離しやすいです。

pipx install poetry
poetry --version

プロジェクト管理ツール自体をプロジェクトの仮想環境に入れると、少し循環した構成になります。
そのため、まずは pipx で独立させる方が見通しはよいです。

最低限の確認コマンド

環境が分からなくなったら、次を順番に確認します。

which python3
python3 --version
python3 -m pip --version

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

echo "$VIRTUAL_ENV"
pipx list

見たいポイントは次の通りです。

• 今の python が .venv 配下を向いているか
• python3 -m pip がどの Python に紐づいているか
• VIRTUAL_ENV が入っているか
• CLI ツールが pipx 管理になっているか

特に、仮想環境を有効化しているときの python と、通常時の python3 は別物として扱うと混乱しにくいです。

自分用の基本ルール

自分の中では、次のように決めておくと迷いが減ります。

• sudo pip install は基本的に使わない
• プロジェクトを作ったら最初に .venv を作る
• プロジェクトのライブラリは python -m pip install で入れる
• Python 製 CLI ツールはまず pipx を検討する
• .venv は Git に入れない
• 依存関係は requirements.txt や pyproject.toml に残す
• どの Python を使っているか迷ったら which と python -m pip --version を見る

これだけでも、「何となく動いているけれど、どこに何を入れたか分からない」という状態を避けやすくなります。

注意点

venv と pipx だけで、すべての Python 環境問題が解決するわけではありません。

たとえば、次のようなケースでは追加の整理が必要です。

• Python 3.10、3.11、3.12 など複数の本体バージョンを切り替えたい
• プロジェクトごとに厳密な再現性が必要
• Docker 上で実行環境を固定したい
• CI とローカルの差分をなくしたい
• 社内プロキシーや社内証明書の影響を受ける

この場合は、pyenv、Docker、CI 設定、社内ミラーなども含めて考える必要があります。

ただ、最初から全部を入れると学習コストが上がります。
まずは venv でプロジェクトを分け、pipx で CLI を分けるところから始めるのが現実的です。

まとめ

Mac の Python 環境で混乱しやすい原因の一つは、プロジェクトの依存ライブラリと、普段使う Python 製 CLI ツールを同じ場所に入れてしまうことです。

自分は次のように分けると考えやすいです。

• プロジェクトで import するものは venv
• ターミナルでコマンドとして使うものは pipx
• Python 本体のバージョン切り替えが必要になったら pyenv などを検討

最初にこの線引きをしておくだけで、環境構築のトラブルはかなり減らせます。
特に Mac で Python を触り始めた人には、まず venv と pipx の使い分けを覚えるのがおすすめです。