Pythonのpipでライブラリ導入問題を解決する方法｜ AI Systems（エーアイシステムズ）

こんにちは、AIシステムズです。
この記事は、代表コバが現場で対応してきたPython開発・運用の知見をもとに、AIを活用して構成・執筆し、弊社にて最終チェックを行ったものです。

「pipでライブラリを入れたのにimportできない」「インストールしたバージョンが思ったものと違う」「ビルドエラーで止まる」——Pythonを業務で使い始めた現場でほぼ必ず通る関門です。原因の大半は、システムPythonと仮想環境の混同、Pythonのバージョン違い、ネイティブビルドの依存不足のいずれかです。

pipインストールの典型的なつまずき
仮想環境（venv・virtualenv）の正しい使い方
pyenvでPythonバージョンを管理する
ビルドエラーへの対処（mysqlclient、Pillow等）
本番環境で再現性を保つ仕組み

pipインストールでつまずく典型パターン

弊社が中小企業のPython導入で対応してきた中で、つまずきは次のパターンが多いです。

pip install をシステムPythonで実行してしまい、複数のプロジェクトでバージョンが衝突
python と pip の指す先がずれていて、入れたつもりが別の環境に入っている
WindowsとmacOS/Linuxでパッケージ名の挙動が違う
権限不足で Permission denied、慌てて sudo pip install を使ってシステムを汚す
ネイティブビルドが必要なパッケージで、開発ヘッダ（gcc, python3-dev等）が足りずビルド失敗

仮想環境を必ず使う

プロジェクトごとに仮想環境を作るのは、Python開発の基本ルールです。「ちょっとしたスクリプトだから」と仮想環境を省略すると、必ず後で困ります。

python3 -m venv .venv
source .venv/bin/activate    # Linux/macOS
.venv\Scripts\activate       # Windows

pip install -r requirements.txt

仮想環境を有効化してから which python、which pip で、正しい場所を指していることを確認します。

Pythonバージョン管理

python3が指すバージョンはOSによって違うため、プロジェクトで使うバージョンを明示的に管理します。

pyenv（推奨）

pyenv install 3.12.2
pyenv local 3.12.2
python3 -m venv .venv

pyenv local でプロジェクトディレクトリに .python-version ファイルが作られ、そのディレクトリに入るだけで自動的に指定バージョンが有効になります。

poetry・uvなどのモダンツール

近年は poetry や uv といったツールで「Pythonバージョン＋仮想環境＋依存管理」を一括化するのが主流です。中小企業の新規プロジェクトは uv から始めるとシンプルです。

ネイティブビルドエラーへの対処

mysqlclient、Pillow、cryptography などCコードのビルドが必要なパッケージで失敗するケースの典型対処法は次のとおりです。

RHEL/AlmaLinux/Rocky系

sudo dnf install -y gcc python3-devel mysql-devel libjpeg-devel zlib-devel openssl-devel

Debian/Ubuntu系

sudo apt install -y build-essential python3-dev default-libmysqlclient-dev libjpeg-dev zlib1g-dev libssl-dev

macOS

brew install mysql-client jpeg openssl
export LDFLAGS="-L$(brew --prefix mysql-client)/lib"
export CPPFLAGS="-I$(brew --prefix mysql-client)/include"

「ビルド済みwheelが配布されているか」もエラー回避の鍵で、PyPIに該当バージョン・OS・Pythonバージョンのwheelがあれば、これらの開発ヘッダなしで入ります。

本番環境への配布

本番に持っていくときに「ローカルでは動いたのに本番で動かない」を防ぐには、依存を完全に固定します。

pip freeze > requirements.txt
# 本番側
pip install -r requirements.txt

requirements.txt にはバージョンまで含めて記載されるため、本番でもまったく同じ依存が再現できます。本番のシステムPythonに直接入れず、必ず本番でも仮想環境を切るのが鉄則です。

こういう用途に向いている／向いていない

このPython運用整備は、中小企業の業務効率化スクリプト、データ処理バッチ、社内Webツール、AI/機械学習の試行錯誤に直接効きます。年に1回しか動かさないような使い捨てスクリプトでは、ここまで整える必要はありません。

再発防止チェックリスト

プロジェクトごとに仮想環境を切っているか
Pythonバージョンを.python-version等で固定しているか
pip freezeで依存を固定しているか
本番でもシステムPythonに直接入れていないか
ビルドエラーが出るパッケージは、wheelがあるバージョンを選んでいるか

まとめ

pipのトラブルは、システムPythonと仮想環境の混同が大元です。仮想環境を必ず使う・Pythonバージョンを固定する・requirements.txtで依存を固定するの3つを徹底すれば、再現性のトラブルはほぼ起きません。

本記事は、代表コバが中小企業のPython開発・運用の現場で対応してきた知見をもとに、AIを活用して構成・執筆し、弊社にて最終確認を行っています。業務スクリプトの環境整備、機械学習・データ処理基盤の構築、Pythonでの自動化導入について、具体的な状況をふまえた相談を承っています。費用感だけ知りたい方も、お気軽にご相談ください。

AI Systemsへの無料相談はこちら

「何から始めればいいか分からない」段階からでも、お気軽にご相談ください。
まずは、お話を聞かせていただくだけでも大丈夫です。

無料で相談する

コバ

AI活用 / Web制作 / 業務自動化支援

中小企業さま向けに「お手頃に・早く・成果が出る」開発支援を行っています。AI・Web・自動化の3分野を、まとめてサポートしています。

Pythonのpipでライブラリ導入問題を解決する方法

目次