macOSでmysqlclientをPython 3向けに正常インストールする手順

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.dyliblibssl.dylibが使用される場合があります。実際のライブラリファイル名はls $(brew --prefix openssl)/lib/で確認してください。

タグ: mysqlclient macOS Python3 install_name_tool mysql_config

8月3日 07:14 投稿