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.
- 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. - If your
.venv
was created from a virtual environment manager likeuv
, it will use the default python installation's sqlite version, e.g.3.13.7
ships withsqlite 3.49.1
- 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
- Use
homebrew
's most recent sqlite installation - Create a python executable using the above sqlite installation
- 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.