{"id":1856,"library":"pip-system-certs","title":"pip-system-certs","description":"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.","status":"active","version":"5.3","language":"python","source_language":"en","source_url":"https://github.com/pypa/pip-system-certs","tags":["security","certificates","tls","networking","pip","truststore","ssl"],"install":[{"cmd":"pip install pip-system-certs","lang":"bash","label":"Install into Python environment"}],"dependencies":[{"reason":"Provides the core functionality for accessing and managing system certificate stores.","package":"truststore","optional":false}],"imports":[{"note":"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.","wrong":"pip_system_certs.enable_system_certs()","symbol":"pip_system_certs","correct":"import pip_system_certs"}],"quickstart":{"code":"# IMPORTANT: Before running this code, install pip-system-certs and requests:\n# python -m pip install pip-system-certs requests\n\nimport requests\nimport sys\n\nprint(f\"Python version: {sys.version.splitlines()[0]}\")\nprint(\"Attempting to fetch https://pypi.org to verify system certificate usage...\")\n\ntry:\n    # requests uses urllib3, which pip-system-certs patches to use system certificates.\n    response = requests.get(\"https://pypi.org\", timeout=10)\n    response.raise_for_status() # Raise an exception for HTTP errors (4xx or 5xx)\n\n    print(f\"Successfully connected to pypi.org! Status: {response.status_code}\")\n    print(\"This indicates that pip-system-certs (via truststore) is likely active, enabling requests to use your system's trusted certificates.\")\n\nexcept requests.exceptions.SSLError as e:\n    print(f\"SSL Error encountered: {e}\")\n    print(\"This suggests pip-system-certs might not be correctly configured, system certificates are invalid, or it's not active.\")\nexcept requests.exceptions.RequestException as e:\n    print(f\"A general request error occurred: {e}\")\n    print(\"Please check your network connection and confirm pip-system-certs is installed.\")","lang":"python","description":"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."},"warnings":[{"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.","message":"pip-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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade your Python environment to version 3.10 or newer to use `pip-system-certs`.","message":"Requires 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.","severity":"breaking","affected_versions":"<5.0 (implicit, as earlier versions might have different truststore requirements), but 5.x explicitly requires >=3.10"},{"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.","message":"The library works by monkey-patching `urllib3`. This approach can potentially conflict with other libraries or custom code that also modifies `urllib3`'s internal behavior.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'5.3':50 'achiev':22 'allow':29 'applic':33 'automat':9 'bundl':44 'cert':4,8 'certif':15,43,71 'configur':10 'conjunct':60 'current':47 'depend':69 'librari':19 'like':36 'monkey':26 'monkey-patch':25 'network':73 'often':58 'os':41 'os-provid':40 'patch':27 'per':56 'pip':2,6,30,64,74 'pip-system-cert':1,5 'primarili':21 'provid':42 'python':11 'releas':55 'request':37 'respect':39 'secur':70 'see':53 'sever':54 'ssl':76 'system':3,7,14 'tls':72 'truststor':18,68,75 'typic':52 'under':67 'updat':62 'urllib3':28,35 'use':13 'util':34 'version':49 'via':16 'year':57","created_at":"2026-04-09T05:08:14.250868+00:00","updated_at":"2026-04-16T18:02:09.056197+00:00","problems":[{"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.","cause":"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.","error":"SSLError(SSLCertVerificationError(1, '[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:XXXX)'))"},{"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`.","cause":"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.","error":"pip-system-certs does not work with requests version >= 2.32.0"},{"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`.","cause":"`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.","error":"UserWarning: Failed to patch SSL settings for unverified requests (unsupported version of urllib3?)"},{"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.","cause":"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.","error":"ERROR: To use the truststore feature, 'truststore' must be installed into pip's current environment."}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"5.3","cli_name":"","cli_version":null,"type":"library","homepage":"https://gitlab.com/alelec/pip-system-certs","github":null,"docs":null,"changelog":null,"pypi":"https://pypi.org/project/pip-system-certs/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["http-networking","auth-security"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-28","next_check":"2026-07-28","install_tag":null}}