How to Fix “Library not found” in Xcode

When Xcode shows “Library not found for -l…” during a build, the linker cannot locate a required static or dynamic library. This guide explains the most common causes, how to diagnose the problem, and several practical ways to fix it.

Typical error message

ld: library not found for -lExample
clang: error: linker command failed with exit code 1

Common causes

• Library Search Paths contains an invalid or outdated directory.
• A required library is missing from Link Binary With Libraries.
• Other Linker Flags still contains an obsolete -l option.
• CocoaPods or another dependency manager did not generate the expected library.
• The library does not support the target architecture or SDK.
• The library file was moved or deleted while Xcode still references its old location.

Typical situations where it appears

This error often appears after moving a project to another Mac, changing a library location, updating CocoaPods, switching build configurations, or inheriting old .xcconfig and Build Settings values.

How to diagnose the error

1. Identify the -l option in the message

If the error says “library not found for -lExample”, the linker is typically trying to find a file such as libExample.a or libExample.dylib. Start by identifying the exact library name from the build log.

2. Check Library Search Paths

Select the target, open Build Settings, and search for “Library Search Paths”. Remove paths that no longer exist and check for machine-specific absolute paths left over from another environment.

3. Check Link Binary With Libraries

Open Target > Build Phases > Link Binary With Libraries. Verify that the required library is present and that there are no broken or red references.

4. Check Other Linker Flags

Search Build Settings for Other Linker Flags and look for obsolete entries such as “-lExample”. If the project uses .xcconfig files, inspect those files as well.

Solutions

Solution 1: Fix or remove invalid Library Search Paths

Delete paths that no longer exist. If a custom library is stored inside the project, prefer project-relative settings instead of a user-specific absolute path.

$(PROJECT_DIR)/Libraries
$(SRCROOT)/Vendor/lib

Solution 2: Re-add the library to Link Binary With Libraries

Remove a broken reference, then use the “+” button to add the correct library or XCFramework again. For a custom library, also verify that the actual file exists at the expected location.

Solution 3: Remove obsolete -l linker flags

If Other Linker Flags still contains a library that the project no longer uses, remove that entry.

OTHER_LDFLAGS = $(inherited)

Solution 4: Reinstall CocoaPods dependencies

If the missing library comes from CocoaPods, verify the Podfile and Podfile.lock, then regenerate the dependencies.

pod install
pod update ExamplePod

If necessary, regenerate the Pods directory.

rm -rf Pods
pod install

Solution 5: Clear Derived Data and rebuild

After fixing paths or dependencies, stale build data can still cause confusing linker failures. Delete Derived Data and rebuild.

rm -rf ~/Library/Developer/Xcode/DerivedData/*

Then run Product > Clean Build Folder in Xcode and build again.

Solution 6: Verify architecture support

Older .a or .dylib files may not contain the architecture required by Apple Silicon, iOS devices, or the iOS Simulator. If the vendor provides a current XCFramework, prefer that version.

lipo -info path/to/libExample.a

Important notes

Also distinguish “Library not found” from “Framework not found”. A “-l…” failure usually points to Library Search Paths or linker flags, while “-framework …” commonly involves Framework Search Paths.

Summary

“Library not found” means the linker cannot find the library requested by the build settings. Check the library name in the “-l…” message first, then review Library Search Paths, Link Binary With Libraries, and Other Linker Flags. If CocoaPods is involved, regenerate dependencies, and if the configuration has already been fixed, clear Derived Data and rebuild.