Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Flutter and app store releases

Xcode fails to link with 'library not found for -lPods' or 'framework not found Pods'

Errorld: library not found for -lPods

Short answer

The linker is looking for the Pods library and nothing is there to link. Check the title bar first: you must build from the .xcworkspace, not the .xcodeproj. If that is right, check the Pods folder is not empty, that your build settings keep $(inherited), and that the Pods target is built before your app in the scheme.

  • Applies to CocoaPods 1.16, Xcode 16, Xcode 26
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Check which file you opened and whether the Pods build products and the workspace exist next to the Podfile.

    ls -d *.xcworkspace Pods Pods/Pods.xcodeproj
    ls Pods/Target\ Support\ Files
  2. 2Match what you see, then jump to its fix

    1. 1The window title shows MyApp.xcodeproj, and the Pods project is missing from the navigator.You built the .xcodeproj instead of the .xcworkspaceFix
    2. 2Workspace is open, Pods project is there, and the error is still library not found for -lPods.Xcode does not see the Pods target as a dependency of the appFix
    3. 3Pods/ exists but a pod's folder inside it has no files.The Pods folder is empty or a pod was never downloadedFix
    4. 4Other linker flags or library search paths were edited by hand, and the Pods flags are missing.Your build settings replace the values from Pods.xcconfigFix

What does the error look like?

  • ld: library not found for -lPods
  • ld: library not found for -lPods-MyApp
  • ld: framework not found Pods
  • clang: error: linker command failed with exit code 1 (use -v to see invocation)

Cause 1 of 4

You built the .xcodeproj instead of the .xcworkspace

1Check

pod install creates a workspace that contains your project and the Pods project. Without it Xcode does not know the Pods target exists, so the link step finds no library.

ls -d *.xcworkspace
open MyApp.xcworkspace

2Fix

Close the project window and open the workspace. Use it every day from now on.

osascript -e 'quit app "Xcode"'
open MyApp.xcworkspace

3Verify

The navigator shows both MyApp and Pods. Clean the build folder (Shift+Command+K) and build again.

xcodebuild -workspace MyApp.xcworkspace -scheme MyApp -destination 'generic/platform=iOS Simulator' build

Confirmed by guides.cocoapods.org

Did this fix it?

Cause 2 of 4

Xcode does not see the Pods target as a dependency of the app

1Check

CocoaPods' troubleshooting guide says this error means Xcode did not detect the implicit dependency. Open Product > Scheme > Edit Scheme > Build and see whether the Pods library is listed above your app.

xcodebuild -workspace MyApp.xcworkspace -list

2Fix

In Edit Scheme > Build, add the Pods static library and move it to the top of the list. Then clean and build.

# Xcode UI: Product > Scheme > Edit Scheme... > Build
# + (add) Pods-MyApp, drag it above MyApp
xcodebuild -workspace MyApp.xcworkspace -scheme MyApp clean

3Verify

The build passes the link step.

xcodebuild -workspace MyApp.xcworkspace -scheme MyApp -destination 'generic/platform=iOS Simulator' build

Confirmed by guides.cocoapods.org

Did this fix it?

Cause 3 of 4

The Pods folder is empty or a pod was never downloaded

1Check

List the folder of the pod named in the error. The troubleshooting guide says an empty folder means the source was not pulled from its git repository.

ls Pods/NameOfPod

2Fix

Reinstall from the lockfile. If a folder is still empty, check the source URL in the pod's podspec.

rm -rf Pods
pod install

3Verify

The pod folder now holds source files.

ls Pods/NameOfPod

Confirmed by guides.cocoapods.org

Did this fix it?

Cause 4 of 4

Your build settings replace the values from Pods.xcconfig

1Check

If a setting such as Other Linker Flags is set on the target without $(inherited), it overrides what the Pods xcconfig adds.

grep -n 'OTHER_LDFLAGS\|LIBRARY_SEARCH_PATHS' MyApp.xcodeproj/project.pbxproj

2Fix

Start each list value in Xcode's Build Settings with $(inherited), then add your own entries after it.

OTHER_LDFLAGS = $(inherited) -ObjC
LIBRARY_SEARCH_PATHS = $(inherited) $(PROJECT_DIR)/libs

3Verify

Build again; the link step finds the Pods library.

xcodebuild -workspace MyApp.xcworkspace -scheme MyApp -destination 'generic/platform=iOS Simulator' build

Confirmed by guides.cocoapods.org

Did this fix it?

How do I stop it coming back?

  • Open only the .xcworkspace. Remove the .xcodeproj from your Dock and recent files.
  • Commit Podfile and Podfile.lock, and run pod install after every pull that changes them.
  • Prefix every hand-edited build setting list with $(inherited).

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Related fixes

Mobile apps

App record creation fails because you lack permission

You cannot add a new app in App Store Connect as a Developer or limited user

Only the Account Holder, an Admin or an App Manager can create an app record, and Apple blocks it until the Account Holder has signed the latest agreement.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.