Installing ObjectBox

Learn how to set up ObjectBox in your project.

Having problems installing ObjectBox using this guide? Please, let us know where we lost you. Thanks for your help!

Adding the ObjectBox Framework to Your Project

We recommend to setup ObjectBox using CocoaPods. Other alternatives are Carthage (see below) or a manual setup in Xcode. Note that Swift Package Manager does not yet support binary frameworks and thus is not an option yet.

If you are familiar with CocoaPods or Carthage, here's the quick setup (details below):


ObjectBox is installed like any other pod, with the exception of an additional 3rd step:

  1. Add pod 'ObjectBox' to the Podfile in your Xcode project directory.

  2. Run pod install in Terminal.

  3. Run Pods/ObjectBox/setup.rb in Terminal.

  4. Open your .xcworkspace.

We also support installation using Carthage. Setup using Carthage works like any other Carthage dependency, with one extra step:

  1. Add github "objectbox/objectbox-swift" to your Cartfile

  2. Run carthage update to download ObjectBox.

  3. Add either Carthage/Build/Mac/ObjectBox.framework or Carthage/Build/iOS/ObjectBox.framework to the appropriate targets of your project

  4. Run gem install xcodeproj and then run the ObjectBox setup script from Carthage/Build/Mac/OBXCodeGen.framework/setup.rb in your project directory.

Project settings

Because ObjectBox does not include bitcode at this point you need to adjust "Build Settings" in Xcode accordingly. In that tab, ensure "All" is active and search for "bitcode". You will find the "Enable Bitcode" setting which you set to "No".

Otherwise, for some build targets, you will get a build error like this: '.../ObjectBox.framework/ObjectBox' does not contain bitcode. You must rebuild it with bitcode enabled (Xcode setting ENABLE_BITCODE), obtain an updated library from the vendor, or disable bitcode for this target.

Swift 5.0: ObjectBox is built for Swift 5.1 and later. The Swift 5.0 compiler can't handle libraries built for earlier versions and is therefore not supported.

Detailed Instructions


If you don't have CocoaPods already, install it by typing sudo gem install cocoapods in Terminal. If you don't have a Podfile yet, cd into your Xcode project folder and create one using pod init as usual. Now find the # Pods for MyTargetName comment for each target and add the following below it:

pod 'ObjectBox'

Then run:

pod repo update
pod install

The first call will ensure your local copy of the list of available CocoaPods is current, the second call is your usual procedure when adding a new pod to your Podfile that will download the newest release of ObjectBox to your Pods directory and install the pod in your Xcode workspace.

Once you have ObjectBox downloaded, setup.rb will set up the ObjectBox preprocessor in your project for every target with an executable.

You can now open your project's Xcode workspace as usual and follow the rest of this tutorial.

Something doesn't work yet (e.g. pod install fails)? Try updating CocoaPods related things using:

gem update xcodeproj && gem update cocoapods && pod repo update


If you don't have Carthage yet, install it e.g. using Homebrew brew install carthage. If you do not have a Cartfile yet, create a text file named just Cartfile (no .txt suffix) in your project's folder and write the following text into it

github "objectbox/objectbox-swift"

Then open Terminal, cd into the folder containing your project and run

carthage update
gem install xcodeproj

The first call is the typical way to make Carthage download a dependency specified in your Cartfile. Once you have ObjectBox downloaded, setup.rb will set up the ObjectBox preprocessor in your project for every target with an executable. The gem install xcodeproj line installs a helper tool needed by the setup script.

Like for all Carthage projects, you now need to open your project in Xcode and add the framework to your target. You do this by dragging either the Carthage/Build/iOS/ObjectBox.framework or Carthage/Build/Mac/ObjectBox.framework (depending on whether your project is for iOS or macOS) to the "Frameworks, Libraries and Embedded Content" list of the "General" tab of your target's settings (On macOS, make sure you choose "Embed and Sign" to its right).

You can now open your project's Xcode workspace as usual and follow the rest of this tutorial.

The steps above are only needed when initially setting up your project. Even after calling carthage update to fetch a newer version of ObjectBox, you do not need to run the setup script anymore, and the gem install xcodeproj line is only needed to be able to run the setup script, so is also unnecessary. Once a project is set up, it can be used by any other developer like any other Carthage project.

Ignore the OBXCodeGen.framework that you'll also see in Carthage/Build. It is not intended to be linked into your application and only exists to hold the code generator and setup script so you have them while you build.