How to Add Xcframework to Ios Project
The quickest way to how to add xcframework to ios project is to add the XCFramework to Xcode, link it in your target, and embed it only if the framework is dynamic. After that, import it in your code and run a simulator and device build to confirm everything is wired correctly. Most setup problems come from choosing the wrong embed setting or using an incompatible architecture.
What an XCFramework is
An XCFramework is Apple’s packaging format for distributing binary frameworks across multiple platforms and architectures. Instead of shipping one framework that tries to support everything, an XCFramework can contain separate slices for iOS devices, simulators, macOS, and other Apple platforms. This makes it easier to support both Intel and Apple Silicon development machines, along with different build destinations.
For iOS projects, an XCFramework is commonly used when you integrate a third-party SDK, a prebuilt internal library, or a binary framework that you do not want to compile from source inside your app target.
Before you start
Before adding the framework, confirm a few basics:
- You have the
.xcframeworkfolder or package file from the vendor or build process. - You are using a recent version of Xcode that supports XCFrameworks.
- You know whether the framework is static or dynamic, because that changes how you embed it.
- You know which target should use it, especially if your Xcode project has multiple app, extension, or test targets.
How to add an XCFramework to Xcode
The exact steps depend on whether the XCFramework is distributed as a standalone file or via a package manager, but the manual Xcode workflow is the same in most projects.
1. Add the XCFramework to your project
Drag the .xcframework folder into the Project Navigator in Xcode. When prompted, choose whether to copy items into your project’s folder. In many app projects, copying the file into the project keeps the dependency easier to manage.
Make sure the framework appears in the Project Navigator and not just on disk. If Xcode does not reference it, the target will not be able to link against it.
2. Add it to your target
Select your app target, then open the General tab. In the Frameworks, Libraries, and Embedded Content section, add the XCFramework if it is not already listed. This is the most common place to confirm that your target knows about the binary.
If Xcode adds the framework automatically when you drag it into the project, still verify that it is attached to the correct target. A file in the project navigator is not enough on its own.
3. Choose whether to embed it
This is the step people get wrong most often. Whether you should embed the XCFramework depends on whether it is static or dynamic:
- Static XCFramework, link it, but do not embed it.
- Dynamic XCFramework, link it and embed it, usually with code signing if required.
If you are not sure which type you have, check the vendor documentation or inspect the framework package. Embedding a static framework is usually unnecessary, while failing to embed a dynamic framework often causes a runtime crash or a missing framework error when the app launches.
4. Confirm Build Phases settings
Open the Build Phases tab for your target and check the following:
- Link Binary With Libraries should include the XCFramework.
- Embed Frameworks should include it only if the framework is dynamic and must be bundled with the app.
- If the framework is embedded, the usual setting is Embed & Sign for app targets that need code signing.
For many projects, Xcode manages these settings automatically. Still, it is worth checking them manually, especially after migrating between project versions or changing targets.
Link and embed the framework correctly
Linking and embedding are related, but they are not the same thing.
| Action | What it does | When to use it |
|---|---|---|
| Link | Tells the compiler and linker that your code uses symbols from the framework | Always required when your code imports and uses the framework |
| Embed | Copies the framework into the app bundle so it is available at runtime | Required for dynamic frameworks, usually not needed for static frameworks |
| Code sign | Signs the embedded framework so iOS can trust it at runtime | Usually required when embedding frameworks in app targets |
A good rule of thumb is simple: if the framework is dynamic, it must be present in the app bundle at runtime. If it is static, it is compiled into your app binary and does not need to be shipped as a separate file.
Import and use the framework in your code
Once the XCFramework is added to the target, you can usually import it in Swift with a standard import statement:
import FrameworkName
For Objective-C projects or mixed projects, the framework header access depends on how the binary was built and exposed. If the framework supports Objective-C interop, you may use the generated module import or a bridging header, depending on the package design.
If the import fails, the framework may not be linked to the correct target, or the module name may be different from the file name. Check the vendor’s instructions for the exact module name.
Example usage
After importing, use the framework’s public types and APIs just like you would with any other module:
let client = SDKClient()
The exact class names, methods, and initialization steps depend on the framework you are integrating. Always follow the vendor’s API reference if one is provided.
Framework search paths and build settings
In many modern Xcode projects, you do not need to manually set framework search paths if the XCFramework is added properly through the target settings. However, you may need to review build settings in older projects or custom build setups.
Useful settings to check include:
- Framework Search Paths, if Xcode cannot locate the binary.
- Library Search Paths, in cases where the package depends on additional binary libraries.
- Runpath Search Paths, especially for dynamic frameworks that must load at runtime.
If you find yourself adding manual search paths just to make the project build, pause and verify that the XCFramework was added to the correct target and that the package structure is intact. Manual paths can hide a setup problem rather than solve it.
How to verify the XCFramework is integrated correctly
After setup, do a quick validation pass:
- Build the app for a simulator destination.
- Build the app for a physical iPhone or iPad device.
- Confirm that the framework imports without compiler errors.
- Launch the app and confirm there is no runtime “framework not found” issue.
- Check the app bundle or build log if the framework is supposed to be embedded.
A successful integration usually means the app builds cleanly in both simulator and device configurations, and the framework’s APIs are available in your code without extra workarounds.
Common XCFramework errors and fixes
Most XCFramework problems fall into a few predictable categories. Use this troubleshooting guide to narrow them down quickly.
| Error or symptom | Likely cause | What to fix |
|---|---|---|
| Framework not found | The framework is not linked, not embedded when needed, or the target cannot see it | Check target membership, Link Binary With Libraries, and Embed Frameworks |
| Unsupported architecture | The XCFramework slice does not contain the destination you are building for | Use a framework that includes the correct simulator or device slice |
| Module not found on import | The module name is wrong or the binary is not exposed properly | Verify the module name and confirm the framework was added to the correct target |
| App crashes on launch after building | A dynamic framework was not embedded or signed correctly | Set the framework to Embed & Sign if required |
| Duplicate symbols or linker conflicts | The framework is linked more than once, or a static library is being included twice | Remove duplicate references and review other dependencies |
XCFramework vs framework
A standard framework is typically packaged for one platform or one set of architectures. An XCFramework is a container format that can hold multiple framework variants in one distribution.
For iOS development, XCFrameworks are usually the safer choice when distributing binary dependencies because they avoid the old problem of combining incompatible slices into one framework file. They are also better suited for modern Apple platform builds that target both devices and simulators.
| Aspect | Framework | XCFramework |
|---|---|---|
| Architecture support | Usually one set of slices | Multiple platform and architecture slices in one package |
| Simulator and device support | Can be limited or require manual setup | Designed to handle both cleanly |
| Xcode integration | Can work, but may be less flexible | Preferred for modern binary distribution |
| Typical use | Single-platform or older packaging | Cross-architecture Apple platform distribution |
Best practices for adding XCFrameworks
- Keep the XCFramework versioned and documented in your project notes.
- Confirm whether the dependency is static or dynamic before changing build settings.
- Test both simulator and device builds, not just one destination.
- Avoid unnecessary manual search paths unless the vendor explicitly requires them.
- Review the framework’s release notes when updating versions, especially if the module name or supported architectures changed.
Frequently Asked Questions About how to add xcframework to ios project
How do I add an XCFramework to an iOS project in Xcode?
Add the .xcframework to your project, attach it to the correct target, then link it in Frameworks, Libraries, and Embedded Content. If it is dynamic, embed and sign it as well.
Do I need to embed an XCFramework in my app?
Only if the XCFramework is dynamic. Static XCFrameworks are linked into the app binary and usually do not need to be embedded.
What is the difference between a framework and an XCFramework?
A framework is a binary package for one platform or architecture set. An XCFramework can package multiple variants together, which makes it more reliable for device and simulator builds.
Why does Xcode say framework not found or unsupported architecture?
This usually means the framework is not linked correctly, the wrong architecture slice is being used, or the XCFramework does not include support for your current build destination.
Can I use an XCFramework with Swift and Objective-C?
Yes, if the framework was built to support those languages. In Swift, you usually import the module directly. In Objective-C, support depends on how the framework exposes its headers and module map.
How do I verify that an XCFramework is linked correctly?
Build the app for both simulator and device, confirm the import works in code, and check that the app launches without runtime framework loading errors.
Conclusion
To add an XCFramework to an iOS project, the main job is to add it to Xcode, link it to the right target, and embed it only when the framework is dynamic. From there, verify the import, test on simulator and device, and fix any architecture or signing issues early. If you follow those steps in order, most XCFramework integrations are straightforward and stable.
