A newer version of this documentation is available.

Install Couchbase Lite on Swift

March 16, 2025

+ 12

Description — Installing Couchbase Lite on Swift

Get Started

Create or open an existing Xcode project and install Couchbase Lite using one of the Install Methods methods shown.

Xcode 12.3 Work Around

If you have downloaded a .framework package to install, you may be impacted by an existing issue in Xcode 12.3. The issue prevents use of certain frameworks, displaying the error: Building for iOS Simulator, but the linked framework was built for iOS — see: Apple Developer Forum.

The recommended solution is to use an .xcframework package, where possible. Alternatively, as an interim solution, you can do the following workaround in your Xcode project:

Navigate to the target’s Build Settings
Locate the Validate Workspace setting
Set Validate Workspace to Yes, then return it to No

Install Methods

Frameworks
Carthage
CocoaPods
Swift Package Manager

Download Couchbase Lite.
Unzip the file
Drag CouchbaseLiteSwift.framework from your Finder to the Xcode navigator.
Click on Project > General > Embedded Binary and add CouchbaseLiteSwift.framework to this section.
Import the framework
```
swift
Copy
import CouchbaseLiteSwift
...
```
Start using Couchbase Lite on Swift in your project.

Install Carthage using the instructions here:
https://github.com/Carthage/Carthage#installing-carthage

In your Cartfile, add the appropriate 'binary' URL:

Couchbase Lite Community Edition

ruby
Copy
binary "https://packages.couchbase.com/releases/couchbase-lite-ios/carthage/CouchbaseLite-Community.json" ~> 2.8

Couchbase Lite Enterprise Edition

ruby
Copy
binary "https://packages.couchbase.com/releases/couchbase-lite-ios/carthage/CouchbaseLite-Enterprise.json" ~> 2.8

Run carthage update --platform ios.
Drag CouchbaseLiteSwift.framework from Carthage/Build/ to the Xcode navigator.
Select Project General Embedded Binary, add CouchbaseLiteSwift.framework to this section.

Install CocoaPods using the instructions here:
https://guides.cocoapods.org/using/getting-started.html

Add one of these targets to your Podfile:

Couchbase Lite Community Edition

ruby
Copy
target 'Example' do
  use_frameworks!
  pod 'CouchbaseLite-Swift', '~> 2.8'
end

Couchbase Lite Enterprise Edition

ruby
Copy
target 'Example' do
  use_frameworks!
  pod 'CouchbaseLite-Swift-Enterprise', '~> 2.8'
end

Install the pods and open the .xcworkspace file generated by CocoaPods, using:
```
bash
Copy
pod install
```

Using Swift Package Manager to install CouchbaseLiteSwift requires Xcode 12+

This tab explains how to include the CouchbaseLiteSwift package within your app
See: Use Case 1. Include in Existing Swift Package | Use Case 2. Include in Your App Project

Use Case 1. Include in Existing Swift Package

Here we will add the CouchbaseLiteSwift dependency to your Parent Swift package — see: Example 1 for the sample manifest.

Add the CouchbaseLiteSwift package as dependency by including the following in the parent package manifest:

swift
Copy
dependencies: [
  .package(name: "CouchbaseLiteSwift",
    url: "insert Couchbase Lite URL", (1)
    from: "2.8.0"),
  ],

1	Insert appropriate Couchbase Lite URL: For Community Edition use: https://github.com/couchbase/couchbase-lite-ios.git For Enterprise Edition use: https://github.com/couchbase/couchbase-lite-swift-ee.git

Add the dependent package product name, to the target:

swift
Copy
targets: [
  .target(name: "ParentPackage",
    dependencies: ["CouchbaseLiteSwift"]),
  ]

Import CouchbaseLiteSwift, and use it:

swift
Copy
import CouchbaseLiteSwift

class ParentPackageSomeClass {
  func someFunction() {
    let db = try! Database(name: "testdb")
    print(">> opening the db: \(db.name)")
  }
}

Example 1. Simple Manifest

swift
Copy
// swift-tools-version:5.3
import PackageDescription
let package = Package(
name: "ParentPackage",
products: [
  .library(
    name: "ParentPackage",
    targets: ["ParentPackage"]),
  ],
dependencies: [
  .package(name: "CouchbaseLiteSwift",
    url: "https://github.com/couchbase/couchbase-lite-swift-ee.git", from: "2.8.0"),
  ],
targets: [
  .target(
    name: "ParentPackage",
    dependencies: ["CouchbaseLiteSwift"]),
  .testTarget(
    name: "ParentPackageTests",
    dependencies: ["ParentPackage"]),
  ]
)

Use Case 2. Include in Your App Project

Here we will add CouchbaseLiteSwift directly into your app

Open the project to which you are going to add CouchbaseLiteSwift
Open the Project Editor to add a dependency
1. In Project Navigator:
  Select your Xcode project file (for example, HostApp in the example)
  Xcode opens the Project Editor pane
2. In the Project Editor pane:
  Select Project Swift Packages and + to add the dependency
  Xcode opens the Choose Package Repository dialog
In the Choose Package Repository dialog:
Enter the appropriate Couchbase Lite URL, Next to continue
For example: https://github.com/couchbase/couchbase-lite-swift-ee.git
Enter the Version and Next to continue
Finish to close the Choose Package Repository dialog

Xcode displays the name, version and URL of the added CouchbaseLiteSwift Package
You can now import CouchbaseLiteSwift, and use it in your app

How to . . .

Learn more . . .

Dive Deeper . . .

Forum | Blog | Tutorials