Buf Schema Registry (BSR)

Swift Package Manager/Xcode

The Buf Schema Registry provides generated SDKs for Swift in the form of a Swift Package Manager repository, just like any other Swift library. It generates SDKs automatically when you push schema changes, which eliminates the need to manage a Protobuf toolchain or generate code locally.

See the tutorial for instructions on how to access generated SDKs from the BSR directly.

Setup and usage

Follow the instructions for your package manager of choice below.

No setup is required to start using Buf's generated Swift SDKs with Xcode.

However, Xcode doesn't yet support using the Swift Package Manager CLI and Package.swift for iOS/Mac apps. Dependency management for these targets is still done with git repositories. To account for this, Buf provides a read-only git server for generated SDKs, which is available at the https://buf.build/gen/swift/git host.

If you aren't developing an iOS, macOS, watchOS, or tvOS app and use a Package.swift manifest file to control your package and its dependencies, please use our Swift Package Manager implementation.

Adding a dependency

To find the git URLs for your BSR module, go to the module's SDKs tab, which you can find at https://{host}/{org}/{module}/sdks. Ensure you have the Swift language and the Xcode tab selected.

  1. In your Xcode project, navigate to File > Add Packages....

  2. In the popup window, click into the Search or Enter Package URL text field in the top right and paste the provided SDK's .git URL:

  3. Next, for the Dependency Rule, select Branch and point it to main.

  4. Click Add Package. A new pop-up will appear prompting you to link the SDK's products to your app.

  5. Ensure the library is checked and click Add to confirm the SDK addition (there will only ever be one library). Note that this will automatically add any transitive dependencies.

When using generated SDKs sourced from the read-only git server with Xcode, only use the Branch dependency rule providing the main branch, or the Exact Version dependency rule, providing the SemVer, as the ranging rules will not function.

Note: Since Buf lazily produces a separate git URL for each version of an SDK upon first request, Xcode's auto-update functionality doesn't work with these generated SDKs. To update an SDK, navigate to the module's SDKs tab and get a new link for a new version. Then manually update the dependency by replacing the existing SDK with the SDK sourced from the new link.

To find the references for your BSR module to use with Swift Package Manager, go to the module's SDKs page, which you can find at https://{host}/{org}/{module}/sdks. Ensure you have the Swift language and the SPM tab selected.


To enable Swift Package Manager to properly resolve all dependencies with the buf scope, set up the project registry with the following command:

$ swift package-registry set https://buf.build/gen/swift --scope=buf

Adding a dependency

Add a dependency on the generated SDK:

  1. Add a package dependency to the dependencies block of your Package.swift manifest file:

    dependencies: [
            id: "buf.connectrpc_eliza_connectrpc_swift",
            exact: "0.8.0-20230913231627-233fca715f49.1"
  2. Add a product dependency to the dependencies block of your target's entry:

        name: "ExamplePackage",
        dependencies: [
                name: "Connectrpc_Eliza_Connectrpc_Swift",
                package: "buf.connectrpc_eliza_connectrpc_swift"

Private generated SDKs

When using SDKs generated from private BSR repositories, you'll need to authenticate by including a personal API token for local use or a Bot user's API token for CI workflows. See the Authentication page for instructions.

When you attempt to access a private BSR module's generated SDKs with Xcode, a prompt window will appear. In the prompt window, ensure that it's requesting your username and password, and not the other VCS-based alternatives (GitHub, GitLab). Supply the username and token in these fields.

To access the private module, execute the following with the swift toolchain, which will associate the token with the registry in the swift configuration file ~/.swiftpm/configuration/registries.json and create a macOS Keychain (or .netrc file) entry to store the credentials locally:

$ swift package-registry login https://buf.build/gen/swift/login --token={token}

The login API was introduced in Swift 5.8. Please ensure your Swift toolchain version is 5.8 or later.

Names and versions

For SDK and product names, as well as available versions for a generated SDK, browse the BSR module's SDKs tab, which you can find at https://{host}/{org}/{module}/sdks. The BSR has a special syntax for generated SDK names and product names:

SPM SDK naming
Xcode SDK naming
Product naming


The version syntax is similar to our other generated SDKs, and is a valid SemVer:

Version syntax
{Plugin version}-{Commit timestamp}-{Commit short name}.{Plugin revision}

To discover SDK versions, you can browse a repository's SDK page, which has installation instructions and an interactive UI.


For commits on branches, the commit timestamp component of the version is always zeroed out to easily differentiate package versions using commits on branches that are not main:

Version syntax for branches
{Plugin version}-Zeroed commit timestamp-{Commit short name}.{Plugin revision}

Available plugins

For a full list of supported plugins, navigate to the BSR plugins page and search for Swift.

To learn more about how these plugins are packaged and distributed, go to the bufbuild/plugins repository. If you find a useful plugin that should be added, file an issue.