macos.md

macOS

This guide explains how to install SQLite on macOS with support for loading extensions.

macOS and xcframework

On recent versions of macOS, the recommended way to load a SQLite extension is through the .xcframework approach, the same method used on iOS.

macOS and dylib

On macOS, dynamic libraries (.dylib) can be loaded at runtime using SQLite’s sqlite3_load_extension API.

Step 1: Add Bridging Header (if using Swift only)

Create a bridging-header.h file:

#include <sqlite3.h>

Set it in your Xcode project under Build Settings → Objective-C Bridging Header.

Step 2: Swift Code to Load Extension

import Foundation
import SQLite3

let dbPath = ":memory:" // or a real file path
var db: OpaquePointer?

if sqlite3_open(dbPath, &db) != SQLITE_OK {
    fatalError("Failed to open database")
}

// Enable loading extensions
if sqlite3_enable_load_extension(db, 1) != SQLITE_OK {
    let err = String(cString: sqlite3_errmsg(db))
    fatalError("Enable extension loading failed: \(err)")
}

// Load the extension
let extensionPath = Bundle.main.path(forResource: "my_extension", ofType: "dylib")!
if sqlite3_load_extension(db, extensionPath, nil, nil) != SQLITE_OK {
    let err = String(cString: sqlite3_errmsg(db))
    fatalError("Extension loading failed: \(err)")
}

print("Extension loaded successfully.")

Python on macOS

The default Python on macOS doesn't support loading SQLite extensions. Install Python from the official package or use Homebrew Python instead:

brew install python

Verify that you are using the Homebrew-installed python3 by running:

which python3

# /opt/homebrew/bin/python3

After installing Python with Homebrew, the python command now uses the Homebrew version. You can now load SQLite extensions in Python as shown in the Python example.

We also offer some of our SQLite extensions as Python packages. You can find them on PyPI at https://pypi.org/user/sqlitecloud/