Skip to main content

A certifi hack to use system trust store on Linux/FreeBSD

Project description

certifi-system-store, a certifi hack to use system trust store

certifi-system-store is a replacement and hack for consumers of certifi. It replaces certifi with an alternative implementation that uses the system trust store on Linux and some BSD distributions.

Please be advised that this package is brand new and highly experimental. It hasn't been tested in any production environment.


You absolutely must run python -m certifi after installing the package. The command ensures that you have a working system trust store and patches your current Python environment. It creates or replaces certifi's dist-info directory with certifi-system-store's dist-info.

I recommend that you install certifi-system-store and patch first, then install your packages and requirements.

$ python -m pip install certifi-system-store
$ python -m certifi
$ python -m pip install requests


The certifi command of certifi-system-store has an additional argument --system-store. The argument is not available with standard certifi package. You can use the property to verify that certifi package is provided by certifi-system-store.

$ python -m venv venv
$ venv/bin/pip install certifi
$ venv/bin/python -m certifi --system-store
usage: [-h] [-c] error: unrecognized arguments: --system-store
$ echo $?
$ venv/bin/pip install certifi-system-store
$ venv/bin/python -m certifi --system-store
$ echo $?

The command also checks for the presence of a CA cert bundle:

$ venv/bin/python -m certifi
Traceback (most recent call last):
FileNotFoundError: /etc/ssl/cert.pem, /etc/pki/tls/cert.pem, /etc/ssl/certs/ca-certificates.crt, /etc/ssl/ca-bundle.pem
$ echo $?

To check for certifi-system-store at runtime:

import certifi

if not getattr(certifi, "__certifi_system_store__", False):
    raise ImportError("certifi-system-store is not installed")

To depend on certifi-system-store:

from setuptools import setup

        "certifi-system-store ; sys_platform == 'linux' or 'freebsd' in sys_platform",
        "certifi > 3000 ; sys_platform == 'linux' or 'freebsd' in sys_platform",

Platform support

Supported platforms

Most major Linux distributions and FreeBSD are supported.

  • Alpine
  • Debian-based distributions (Ubuntu, Raspberry Pi OS, Tails, ...)
  • Fedora-based distributions (RHEL, CentOS, CentOS Streams)
  • FreeBSD
    • NOTE: may require manual installation of ca_root_nss
  • OpenSUSE

Untested platforms

certifi-system-store may work, but there is no CI for these platforms.

  • ArchLinux
  • Gentoo
  • OpenWRT
  • Slackware
  • VoidLinux
  • other Linux distributions not based on Debian or Fedora
  • OpenBSD
  • NetBSD

Unsupported platforms

  • Windows
  • macOS
  • Android (has a cert directory but not a PEM bundle)
  • iOS

Supported system trust stores


  • Alpine
  • Arch
  • Fedora 34+ (see rhbz#1895619)
  • FreeBSD (requires ca_root_nss package)
  • OpenWRT
  • RHEL 9


  • CentOS 7, 8
  • Fedora 33 and earlier
  • RHEL 7, 8


  • Debian (requires ca-certificates package)
  • Gentoo
  • Ubuntu (requires ca-certificates package)


  • SUSE

How to install custom CA certificates


$ sudo cp my-custom-ca.pem /usr/local/share/ca-certificates/my-custom-ca.crt
$ sudo update-ca-certificates


$ sudo cp my-custom-ca.pem /etc/ca-certificates/trust-source/anchors/my-custom-ca.crt
$ sudo update-ca-trust

CentOS, Fedora, RHEL

Standard PEM or DER-encoded certificates (BEGIN CERTIFICATE)

$ sudo cp my-custom-ca.pem /etc/pki/ca-trust/source/anchors/
$ sudo update-ca-trust

Certificates with additional trust information (BEGIN TRUSTED CERTIFICATE)

$ sudo cp my-custom-ca.pem /etc/pki/ca-trust/source/
$ sudo update-ca-trust

Debian, Ubuntu

Note: The man page update-ca-certificates(8) mentions that cert files must have a .crt extension.

$ sudo cp my-custom-ca.pem /usr/local/share/ca-certificates/my-custom-ca.crt
$ sudo update-ca-certificates

How does it work?

  • empty certifi/cacert.pem to override any existing certifi data.
  • fake certifi dist-info with much higher version number than certifi's default dist-info metadata
$ venv/bin/pip install certifi-system-store
$ ls -l .tox/venv/lib/python3.9/site-packages/
$ venv/bin/python -m certifi -v --system-store
certifi-system store 3000.0a1
Patched certifi.dist-info -> certifi_system_store.dist-info
$ ls -l .tox/venv/lib/python3.9/site-packages/
certifi-3000.1.dist-info -> certifi_system_store-3000.1.dist-info

Special thanks

  • Cory Benfield
  • Pradyun Gedam
  • Wouter Bolsterlee

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

certifi-system-store-3021.3.16.tar.gz (18.0 kB view hashes)

Uploaded source

Built Distribution

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page