macOS上でpip3 install mysqlclientを実行した際に、コンパイルエラーまたは実行時ライブラリロード失敗が発生するのは、MySQLクライアントライブラリのパス解決とRPATH設定が不適切な場合が主な原因です。以下に、2つの代表的な障害パターンと、それぞれに対応した確実な解決策を示します。
コンパイルフェーズでpkg-configが失敗する問題
インストール時にpkg-config --exists mysqlclientや同様のコマンドが失敗し、ビルド依存関係の取得に失敗する場合、mysqlclientのソースビルドが中断されます。これは、HomebrewやMySQL公式インストーラーでMySQLを導入した際、pkg-config用の.pcファイルがパス上に存在しないことが原因です。
この状況では、mysql_configコマンドを直接活用してコンパイラフラグを明示的に指定します:
export MYSQLCLIENT_CFLAGS="$(/usr/local/mysql/bin/mysql_config --cflags)"
export MYSQLCLIENT_LDFLAGS="$(/usr/local/mysql/bin/mysql_config --libs)"
pip3 install --no-cache-dir mysqlclient
※ /usr/local/mysql/bin/mysql_config のパスは、MySQLのインストール先に応じて変更してください(例:Homebrewでmysql@8.0をインストールした場合は$(brew --prefix mysql@8.0)/bin/mysql_config)。
import時にdylibがロードできない問題
インストールは成功しても、import MySQLdbで次のようなエラーが出力されることがあります:
ImportError: dlopen(.../_mysql.cpython-39-darwin.so, 0x0002): Library not loaded: @rpath/libmysqlclient.24.dylib
Reason: no LC_RPATH's found
これは、拡張モジュールが動的リンク時に必要なライブラリ(libmysqlclient, libssl, libcrypto)の検索パスが正しく設定されていないためです。単純なシンボリックリンク作成だけでは解決せず、バイナリ自体のRPATHおよび依存ライブラリのインストール名を修正する必要があります。
以下のコマンドで、対象の共有オブジェクトファイルに対してRPATH追加とライブラリ参照先の書き換えを行います:
# RPATHを追加(MySQLライブラリディレクトリを探索パスに登録)
install_name_tool -add_rpath /usr/local/mysql/lib \
~/Library/Python/3.9/lib/python/site-packages/MySQLdb/_mysql.cpython-39-darwin.so
# libsslとlibcryptoの参照先を明示的に置換(OpenSSLはHomebrew経由でインストール済みと仮定)
install_name_tool -change "libssl.3.dylib" "$(brew --prefix openssl)/lib/libssl.3.dylib" \
~/Library/Python/3.9/lib/python/site-packages/MySQLdb/_mysql.cpython-39-darwin.so
install_name_tool -change "libcrypto.3.dylib" "$(brew --prefix openssl)/lib/libcrypto.3.dylib" \
~/Library/Python/3.9/lib/python/site-packages/MySQLdb/_mysql.cpython-39-darwin.so
なお、OpenSSLのバージョンやインストール方法によっては、libssl.3.dylibではなくlibssl.1.1.dylibやlibssl.dylibが使用される場合があります。実際のライブラリファイル名はls $(brew --prefix openssl)/lib/で確認してください。