Registry / http-networking / pip-system-certs

pip-system-certs

JSON →
library5.3pypypi✓ verified 23d ago

pip-system-certs automatically configures Python to use system certificates via the `truststore` library. It primarily achieves this by monkey-patching `urllib3`, allowing `pip` and other applications utilizing `urllib3` (like `requests`) to respect OS-provided certificate bundles. It is currently at version 5.3 and typically sees several releases per year, often in conjunction with updates to `pip` or its underlying `truststore` dependency.

http-networkingauth-security
pip install pip-system-certs
package ↗homepage ↗
INSTALL
IMPORT
SIG · PIP-SYSTEM-CERTS
P
pip-system-certs
http-networkingpythonv5.3
Install
2.1s avg
Import
—
Disk
15MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.9–3.13
musl
3.9–3.13
Install & Compatibility
Where this runs
tested against v5.3 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 16.5MB
glibc
py 3.10–3.95 runs
installs and imports cleanly · install 2.1s · import 0.000s · 17MB
15MB installed
● package 15MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

pip_system_certs
✓ import pip_system_certs
✗ pip_system_certs.enable_system_certs()
The `pip-system-certs` library's primary function is to activate automatically upon installation and Python environment load; it does not typically expose public functions or classes for direct invocation. Importing the module primarily serves to ensure it's loaded, though its effect is side-effectual and generally does not require explicit calls.

Install `pip-system-certs` into your Python environment. Once installed, it automatically configures `urllib3` (and libraries depending on it, like `requests`) to use system certificates. The quickstart code demonstrates this by making an `https` request to a public website, which should succeed if system certificates are correctly utilized.

# IMPORTANT: Before running this code, install pip-system-certs and requests: # python -m pip install pip-system-certs requests import requests import sys print(f"Python version: {sys.version.splitlines()[0]}") print("Attempting to fetch https://pypi.org to verify system certificate usage...") try: # requests uses urllib3, which pip-system-certs patches to use system certificates. response = requests.get("https://pypi.org", timeout=10) response.raise_for_status() # Raise an exception for HTTP errors (4xx or 5xx) print(f"Successfully connected to pypi.org! Status: {response.status_code}") print("This indicates that pip-system-certs (via truststore) is likely active, enabling requests to use your system's trusted certificates.") except requests.exceptions.SSLError as e: print(f"SSL Error encountered: {e}") print("This suggests pip-system-certs might not be correctly configured, system certificates are invalid, or it's not active.") except requests.exceptions.RequestException as e: print(f"A general request error occurred: {e}") print("Please check your network connection and confirm pip-system-certs is installed.")
Debug
Known issues
gotchapip-system-certs will not override existing certificate configurations set via `PIP_CERT` environment variable or the `cert` option in `pip.conf`. It's intended for environments not already using a custom certificate bundle.
fix
Ensure `PIP_CERT` is unset and no `cert` option is configured in `pip.conf` if you intend for pip-system-certs to manage certificates. If custom certificates are needed, manage them manually or through environment configurations.
affects: All versions
breakingRequires Python 3.10 or higher. The underlying `truststore` library leverages features specific to modern Python versions, making `pip-system-certs` incompatible with older Python runtimes.
fix
Upgrade your Python environment to version 3.10 or newer to use `pip-system-certs`.
affects: <5.0 (implicit, as earlier versions might have different truststore requirements), but 5.x explicitly requires >=3.10
gotchaThe library works by monkey-patching `urllib3`. This approach can potentially conflict with other libraries or custom code that also modifies `urllib3`'s internal behavior.
fix
Be aware of potential conflicts if other packages in your environment perform deep `urllib3` modifications. Test thoroughly when integrating with complex network stack setups. In case of issues, temporarily uninstall `pip-system-certs` to isolate the problem.
affects: All versions
Errors
Common errors & fixes
SSLError(SSLCertVerificationError(1, '[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:XXXX)'))
This error occurs when pip or a Python application (like requests) cannot verify the SSL certificate of the server it's trying to connect to, often due to corporate proxies, self-signed certificates, or an outdated/missing system certificate store that pip-system-certs is intended to address but isn't.
fix
Ensure `pip-system-certs` is installed with `pip install pip-system-certs`. If the issue persists, verify your system's certificates are up-to-date and correctly configured, especially in corporate environments where custom root CAs might be required. For Python.org installations on macOS, running 'Install Certificates.command' in your Python directory might help.
pip-system-certs does not work with requests version >= 2.32.0
A change in `requests` version 2.32.0 (and newer) optimized certificate verification, which affected how `pip-system-certs` monkey-patches `urllib3` and `requests`, leading to SSL validation errors.
fix
The issue is noted as a compatibility problem. Check the `pip-system-certs` GitLab issues for updates and potential fixes. As a temporary workaround, users have reported success by pinning the `requests` library to an earlier version, such as `requests==2.31.0`.
UserWarning: Failed to patch SSL settings for unverified requests (unsupported version of urllib3?)
`pip-system-certs` relies on monkey-patching `urllib3` to inject system certificate support. This warning indicates that the version of `urllib3` being used is not fully compatible with the patching mechanism implemented by `pip-system-certs`, preventing it from correctly configuring SSL settings.
fix
Ensure `pip-system-certs` and `urllib3` are both updated to their latest compatible versions. Check the `pip-system-certs` project's issue tracker for known incompatibilities with specific `urllib3` versions and any recommended solutions or workarounds. This might also arise if other libraries have already monkey-patched `ssl`.
ERROR: To use the truststore feature, 'truststore' must be installed into pip's current environment.
While `pip-system-certs` leverages `truststore`, this error typically occurs when `pip` itself is explicitly told to use the `--use-feature=truststore` flag, but the `truststore` package (or its vendored version within pip) is not properly available or recognized in the current Python environment for direct use by `pip`'s internal mechanisms before `pip-system-certs` takes effect.
fix
Ensure `pip-system-certs` is installed globally or in the relevant virtual environment (`pip install pip-system-certs`). If still encountering this error when manually trying to use `--use-feature=truststore`, it might indicate an environment issue or a version conflict where `truststore` isn't accessible to `pip`'s bootstrap process. On Python 3.10+, `truststore` is integrated into `pip 24.2+` by default, so ensure `pip` is updated.
Upgrade
Version history
5.3latest on PyPI · released Oct 16, 2025
Audit
Dependencies
truststorerequiredProvides the core functionality for accessing and managing system certificate stores.
Agent activity
32 hits · last 30 days
node
26
Amazon
1
OpenAI (training)
1
Resources
packagehttps://pypi.org/project/pip-system-certs/ ↗
homepagehttps://gitlab.com/alelec/pip-system-certs ↗
pip-system-certs — pip install pip-system-certs · libregistry