Installing ObjectBox

Learn how to set up ObjectBox in your project.

Adding the ObjectBox Framework to Your Project

You can download the ObjectBox framework from our Github releases page or get it via CocoaPods. Setup involves running a single script.

Note: ObjectBox requires at least Swift 5.


Add the following to your Podfile:

pod 'ObjectBox', '1.0.0-rc.7'

If you don't have a Podfile yet, create one using pod init as usual and then add the above line under the # Pods for MyTargetName comment for each target. 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 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 workspace as usual and follow the rest of this tutorial.

Manual Setup

Note: We recommend the setup using CocoaPods (see above). A manual setup is usually not required.


To download the pre-built framework for your project, fetch the version you need from our GitHub releases page:

and drop the extracted files somewhere in your project folder (for example, if your project is at /path/to/MyProject.xcodeproj, you could put ObjectBox at /path/to/ObjectBox ).

Once you have ObjectBox, you do like for any framework and drag the framework from /path/to/ObjectBox/Carthage/Build/iOS/ObjectBox.framework (resp. /path/to/ObjectBox/Carthage/Build/Mac/ObjectBox.framework for a Mac app) into the Linked Frameworks and Libraries list in the General tab of your target's settings in Xcode, and add a Copy Files build phase with Destination set to "Frameworks" into whose file list you also drag the framework.

Setup Script

Then open Terminal and run

gem install xcodeproj /path/to/ObjectBox/setup.rb /path/to/MyProject.xcodeproj TargetName

where TargetName is the name of whatever target in your project you want to use ObjectBox in. (If you leave away the target name, ObjectBox will pick all targets in your project that can be run, so applications)

The first call installs a helper library needed by the installation script to do its work. This library is not needed once you have run the script. Nobody else using your project needs to do this.


You can now open your project and follow the rest of this tutorial.

The Sandbox on macOS

Currently, use of ObjectBox from a sandboxed macOS application requires you to set up at least one App Group for ObjectBox to be able to open a database, in addition to whatever you would normally have done to gain access to the destination folder under the sandbox:

  1. Open your project in Xcode.

  2. Select the project icon at the very to of the Project Navigator.

  3. Select the Capabilities tab where you turned on App Sandbox.

  4. Turn on the switch next to App Groups.

  5. if the App Groups list is empty, Click the little "+" icon to add one.

You should now see a list entry like FGDTDLOBXDJ.$(TeamIdentifierPrefix). If you only see $(TeamIdentifierPrefix) , you still need to set up your team and code-signing under General.

That is all, ObjectBox will pick up the App Group Identifier without any additional work.

You do not need to perform any of these steps for an application running on iOS, or if your macOS application is not sandboxed.