sqlite python

Understanding SQLite Versions on macOS for Python Development

Marcelino Veloso III,

When developing Python applications that use SQLite on a Mac, it’s important to know which version of SQLite your environment is actually running. Different tools install and link different versions, which can affect the availability of newer SQLite features (e.g., JSON1 functions, window functions, STRICT tables, etc.).

1. Homebrew’s SQLite

If you install SQLite via Homebrew, it will provide a recent version of SQLite system-wide.

brew install sqlite
sqlite3 --version
# Example output as of Sept. 2025
# 3.50.4

However, just because Homebrew provides the latest version does not mean your Python interpreter automatically uses it. By default, Python builds on macOS often link to the older system SQLite that ships with macOS.

2. Pyenv with Python Built Against New SQLite

If you use pyenv to manage Python versions, you can build Python so it links against the most recent SQLite (such as the one installed by Homebrew).

For example:

# Example for macOS with Homebrew-installed sqlite
LDFLAGS="-L$(brew --prefix sqlite)/lib" \
  CPPFLAGS="-I$(brew --prefix sqlite)/include" \
  PKG_CONFIG_PATH="$(brew --prefix sqlite)/lib/pkgconfig" \
  PYTHON_CONFIGURE_OPTS="--enable-optimizations" \
  pyenv install 3.13.7

Why these flags?

  • CPPFLAGS points to the SQLite header files so the CPython build can compile against the right headers.
  • LDFLAGS tells the linker where to find the SQLite library so the runtime will use the Homebrew-supplied libsqlite3.
  • PKG_CONFIG_PATH helps tools like pkg-config find the .pc metadata for sqlite.

3. uv venv (Using pyenv’s Python Inside Virtual Environments)

A virtual environment inherits the already-built Python executable it was created with.

  1. If your .venv was created from a pyenv Python built with Homebrew SQLite (as above), import sqlite3 inside the .venv will use the Homebrew-linked SQLite.
  2. If your .venv was created from a virtual environment manager like uv, it will use the default python installation's sqlite version, e.g. 3.13.7 ships with sqlite 3.49.1
  3. If your .venv was created from system Python (not rebuilt), it will use whatever SQLite that system Python was built with.

Combining all of the above

  1. Use homebrew's most recent sqlite installation
  2. Create a python executable using the above sqlite installation
  3. Create the virtual environment using the above python executable
> brew install sqlite
> LDFLAGS="-L$(brew --prefix sqlite)/lib" \
  CPPFLAGS="-I$(brew --prefix sqlite)/include" \
  PKG_CONFIG_PATH="$(brew --prefix sqlite)/lib/pkgconfig" \
  PYTHON_CONFIGURE_OPTS="--enable-optimizations" \
  pyenv install 3.13.7
> uv venv --python $HOME/.pyenv/versions/3.13.7/bin/python

The virtual environment created will now be linked to the most updated sqlite version.