Xcodeでビルド時に「Library not found for -l○○」と表示され、リンク処理に失敗することがあります。このエラーは、リンカが指定された静的ライブラリや動的ライブラリを見つけられないときに発生します。ここでは主な原因、確認手順、複数の解決方法を整理します。
代表的なエラーメッセージ
ld: library not found for -lExample
clang: error: linker command failed with exit code 1主な原因
- Library Search Pathsに古い、または存在しないパスが残っている
- Build PhasesのLink Binary With Librariesに必要なライブラリが正しく追加されていない
- Other Linker Flagsに不要な-l○○指定が残っている
- CocoaPodsなどの依存関係が正しく生成・更新されていない
- ライブラリが対象アーキテクチャやSDKに対応していない
- ライブラリの実体を移動・削除したのにXcode側の参照が残っている
代表的な発生状況
プロジェクトを別のMacへ移した直後、CocoaPodsを更新した後、ライブラリの保存場所を変更した後、古い.xcconfigやBuild Settingsを引き継いだときなどに発生しやすいエラーです。
確認手順
1. エラー中の-l指定を確認する
「library not found for -lExample」であれば、リンカは通常libExample.aやlibExample.dylibなどを探しています。まずエラー名を正確に確認します。
2. Library Search Pathsを確認する
Targetを選択し、Build Settingsで「Library Search Paths」を検索します。存在しない絶対パス、他のMac固有のパス、古いビルド出力先が残っていないか確認してください。
AppleのBuild Settingsでは、Library Search Pathsはリンカがライブラリを検索するディレクトリを指定する設定です。
3. Link Binary With Librariesを確認する
Target > Build Phases > Link Binary With Librariesを開き、必要なライブラリが登録されているか、赤字や壊れた参照がないか確認します。
4. Other Linker Flagsを確認する
Build SettingsのOther Linker Flagsに「-lExample」など不要な指定が残っていないか確認します。
解決方法
方法1：無効なLibrary Search Pathsを削除・修正する
存在しない絶対パスを削除し、必要なら$(PROJECT_DIR)や$(SRCROOT)を使った相対パスへ変更します。
$(PROJECT_DIR)/Libraries
$(SRCROOT)/Vendor/lib方法2：Link Binary With Librariesを追加し直す
壊れたライブラリ参照を一度削除し、「+」から正しいライブラリやXCFrameworkを追加し直します。独自ライブラリの場合はファイル自体がプロジェクト内または指定パスに存在することも確認します。
方法3：不要な-lオプションを削除する
Other Linker Flagsに古い「-lExample」が残っているだけなら削除します。xcconfigを使っている場合はそちらも確認してください。
OTHER_LDFLAGS = $(inherited)方法4：CocoaPodsを再インストールする
CocoaPods経由のライブラリで発生した場合は、PodfileとPodfile.lockを確認したうえで依存関係を再構築します。
pod install
pod update ExamplePod必要に応じてPodsディレクトリを再生成する方法もあります。
rm -rf Pods
pod installCocoaPods利用時は.xcodeprojではなく.xcworkspaceを開いてください。
方法5：Derived Dataを削除して再ビルドする
検索パスや依存関係を修正しても古いビルド情報が残る場合はDerived Dataを削除します。
rm -rf ~/Library/Developer/Xcode/DerivedData/*その後、XcodeでProduct > Clean Build Folderを実行し、再ビルドします。
方法6：アーキテクチャとライブラリ実体を確認する
古い.aや.dylibを使っている場合、Apple SiliconやiOSシミュレータ向けの必要なアーキテクチャを含んでいないことがあります。ライブラリ提供元のXCFramework版や現在のSDK対応版がある場合はそちらを優先してください。
lipo -info path/to/libExample.a注意点
Library Search Pathsへ広すぎる再帰パスを追加すると、別バージョンのライブラリを誤って拾う原因になります。必要なディレクトリだけを指定するのが安全です。
また、Framework not foundはFramework Search Paths側の問題であることが多く、Library not foundとは確認する設定が異なります。エラーが「-framework ○○」か「-l○○」かを見分けてください。
まとめ
「Library not found」は、リンカが指定されたライブラリを検索パス上で見つけられないときに発生します。まずエラー中の「-l○○」を確認し、Library Search Paths、Link Binary With Libraries、Other Linker Flagsの順に見直すのが基本です。CocoaPods利用時は依存関係の再生成、古いキャッシュが疑われる場合はDerived Dataの削除も有効です。
