Installation and customization

Linux/BSD provided

Most Linux & BSD distributions have packaged APSW which may trail the SQLite and APSW releases by a year, or more. The distribution provided APSW uses the system wide SQLite library.

Debian

Install python3-apsw

Fedora

Install python3-apsw

Ubuntu

Install python3-apsw

Gentoo

Install dev-python/apsw

Arch

Install python-apsw

FreeBSD

databases/py-apsw in Ports

There is a full list (150+) of distributions, the package name for APSW, and what APSW version they are currently on.

Source

It is recommended you get the source from Github releases. If you get the source from PyPi then ensure you edit the setup.apsw file inside.

Verifying your download

Github source releases are digitally signed so you can verify they have not been tampered with, and were produced by the project maintainer.

Sigstore is used. Instructions are shown for the standalone cosign tool (easiest, recommended), and the Python sigstore module.

Verify

Checking the signature needs to provide the source release, the cosign bundle, the maintainer id, and issuer. The command is all one line shown here across multiple lines for clarity, along with the expected successful output.

$ cosignverify-blobapsw-3.51.1.0.zip\
--new-bundle-format\
--bundleapsw-3.51.1.0.zip.cosign-bundle\
--certificate-identity=rogerb@rogerbinns.com\
--certificate-oidc-issuer=https://github.com/login/oauth
Verified OK
$ python3-msigstoreverifyidentityapsw-3.51.1.0.zip\
--bundleapsw-3.51.1.0.zip.cosign-bundle\
--cert-identity=rogerb@rogerbinns.com\
--cert-oidc-issuer=https://github.com/login/oauth
OK: apsw-3.51.1.0.zip

Check for a success exit code, and verified message.

Building and customization

APSW is configured for standard building (PEP 518)

$ python3-mbuild

You will need to update the MANIFEST first if you are providing your own SQLite, or if you are providing a setup.apsw with custom configuration. setuptools is used to compile the extension. You can use it directly instead by invoking setup.py.

Build process

A series of commands and options are given to setup.py in this pattern:

pythonsetup.pycmdone--option--optionvaluecmdtwo--option\
cmdthree--option--optionvalue

The only necessary command is build. You can get help by –help:

pythonsetup.pybuild--help

Each command takes options which can be specified on the command line, or in a configuration file named setup.cfg or setup.apsw. The leading double dash on options is omitted, and dashes inside should become underscores.

# This is used with pypi source and binary builds
[build]
# download corresponding sqlite release
fetch=True
# all extensions included
enable_all_extensions=True
# ... except icu (not abi stable)
omit=icu
# for Cursor.description_full
enable=COLUMN_METADATA

SQLite options

It is important to understand SQLite’s compile time options. They provide control over functionality and APIs included or excluded from SQLite.

APSW needs to know the options chosen so it can adapt. For example if extension loading is omitted from SQLite then APSW also needs to omit the same functionality, otherwise compilation or linking will fail.

Finding SQLite

APSW can fetch SQLite as detailed below, and places it in a sqlite3/ subdirectory. You can place your own SQLite in that directory. If there is a sqlite3.c (ie the amalgamation) then it will be statically included inside APSW. A compiled SQLite will be picked up if present. If none of that is present, then the standard compiler locations are used (eg /usr/include on Unix).

If sqlite3/sqlite3config.h is present it is included before sqlite3/sqlite3.c. It is a good location to put platform configuration which APSW’s fetch does automatically by running configure.

setup.py commands and their options

These are the relevant setup.py commands and their relevant options.

build

Does the complete build. This will invoke build_ext - use only one of build or build_ext.

--fetch

Fetches the corresponding SQLite version

--enable-all-extensions

Enables all the standard extensions

--enable

A comma separated list of options to enable that are normally off omitting the SQLITE_ENABLE prefix. They will be uppercased. eg --enable column_metadata,fts5

--omit

A comma separated list of options to omit that are normally enabled omitting the SQLITE_OMIT prefix. They will be uppercased. eg --omit automatic_index

fetch

This provides more fine grained control over what is fetched.

--version

Specify an explicit version of SQLite to fetch

--fetch-sqlite

Downloads the SQLite amalgamation

--all

Downloads all SQLite components other than the amalgamation. Over time this has included additional extensions and SQLite functions, but currently is nothing.

--missing-checksum-ok

APSW includes checksums of SQLite releases and will fail a fetch if you specify a version for which no checksum is known. This allows proceeding.

build_ext

This performs the compilation of the C code, and provides more control than build.

--use-system-sqlite-config

Uses ctypes to determine the system wide SQLite library compilation options

--definevalues

Additional #defines separated by commas. eg --definevalues SQLITE_MAX_ATTACHED=37,SQLITE_EXTRA_INIT=mycore_init

--enable-all-extensions

Enables all the standard extensions

--enable

A comma separated list of options to enable that are normally off omitting the SQLITE_ENABLE prefix. They will be uppercased. eg --enable column_metadata,fts5

--omit

A comma separated list of options to omit that are normally enabled omitting the SQLITE_OMIT prefix. They will be uppercased. eg --omit automatic_index

--apsw-no-old-names

Excludes old non PEP 8 complaint name aliases from the extension and type stubs.

Pyodide

Pyodide is a web assembly Python distribution that can run in the browser or via NPM. PyPI does not support pyodide binary packages yet, but you can compile your own on a Linux host.

You should first download the source distribution listed at the top of https://pypi.org/project/apsw/#files - the filename ends up being apsw-3.47.0.0.tar.gz in this example. The cibuildwheel tool is used for the building, and is the same tool used for the PyPI builds of APSW.

# Startoutwithacleanvirtualenvironment
$ python3-mvenvvenv
# Getcibuildwheel
$ venv/bin/pip3installcibuildwheel
# Dothebuildingwhichwilldownloadthenecessarycompilerand
# Pythonparts
$ venv/bin/cibuildwheel--platformpyodideapsw-3.47.0.0.tar.gz
# Whenithasfinishedtheresultisinthewheelhousedirectory
$ lswheelhouse/

You will then be able to install the wheel using micropip.

>>> importmicropip
>>> await micropip.install("https://url/apsw-3.47.0.0-cp312-cp312-pyodide_2024_0_wasm32.whl")
>>> importapsw

At this point you will be able to use APSW as normal.

Advice for packagers

This is the recommendation for packagers such as Linux and BSD distributions, who want APSW to use the system shared SQLite library.

  • Use the source file from github releases. Note you should use the zip or tar.gz file including the version number, not the github repository copy at the end. The file is signed and can be verified.

    The file also includes a copy of the built documentation in HTML format with no analytics in the doc/ subdirectory.

  • After extracting the zip, replace the file named setup.apsw that sits alongside setup.py with the following contents:

    [build_ext]
use_system_sqlite_config=True

    This will probe the system SQLite shared library for its compilation options. Various C level APIs are included or excluded from the shared library based on those options, so APSW needs to know at compilation time which APIs it can or can’t call.

  • You can compile APSW using whatever works for your packaging system. APSW complies with the latest Python packaging guidelines and metadata. (The traditional setuptools is the build backend.) You will see lines like the following during build (note the Extracting configuration).

    running build_ext
Extracting configuration from libsqlite3.so.0
SQLite: Using system sqlite include/libraries

  • pyproject.toml defines a script entry point (command line tool) for apsw which invokes the Shell. It is optional to package this. A man page is included in the man/ directory.

Testing

SQLite itself is extensively tested. It has considerably more code dedicated to testing than makes up the actual database functionality.

APSW includes tests which use the standard Python testing modules to verify correct operation. New code is developed alongside the tests. Reported issues also have test cases to ensure the issue doesn’t happen or doesn’t happen again. Use python3 -m apsw.tests to run all the tests. You can provide a -v option to see each test as it is run.

Test output will look similar to this.

$ python3 -m apsw.tests
 Python /space/apsw/.venv/bin/python3 sys.version_info(major=3, minor=14, micro=0, releaselevel='final', serial=0) 64bit ELF
Testing with APSW file /space/apsw/apsw/__init__.cpython-314-x86_64-linux-gnu.so
 APSW version 3.51.0.0
 SQLite lib version 3.51.0
SQLite headers version 3051000
 Using amalgamation True
 SQLITE_SCM_BRANCH trunk
 SQLITE_SCM_TAGS release major-release version-3.51.0
 SQLITE_SCM_DATETIME 2025年11月04日T19:38:17.314Z
................................................................................................................................................................................................................
----------------------------------------------------------------------
Ran 208 tests in 44.591s
OK

The tests also ensure that as much APSW code as possible is executed including alternate paths through the code. 95.5% of the APSW code is executed by the tests. In the source, there is a script that enables extra code that deliberately induces extra conditions such as memory allocation failures, SQLite returning error codes, Python APIs erroring etc. That brings coverage up to 99.6% of the code.

Compiler sanitizers options are also used for further validation.

To ensure compatibility with the various Python versions, a script downloads and compiles all supported Python versions in both debug and release configurations (and 32 and 64 bit) against the APSW and SQLite supported versions running the tests.

In short both SQLite and APSW have a lot of testing!