# Standard Library Health Check Module **URL:** \ **Category:** Ideas\ **Created:** [December 1, 2025, 1:41pm UTC](https://discuss.python.org/t/standard-library-health-check-module/105153 "2025-12-01T13:41:28Z")\ **Posts on this page:** 20\ **Page:** 1
**Author:** ![Auberryy](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/auberryy/32/32909_2.png) [@Auberryy](https://discuss.python.org/u/Auberryy)\ **Post date:** [December 1, 2025, 1:41pm UTC](https://discuss.python.org/t/standard-library-health-check-module/105153/1 "2025-12-01T13:41:28Z")
**Abstract** I propose adding a lightweight module to the Python Standard Library to serve as a runtime diagnostic tool. It would verify that the current Python environment is correctly configured, ensure C-extensions are properly linked, and confirm that the underlying OS provides necessary resources (such as entropy, filesystem permissions, network sockets, etc.). **The Problem** Currently, Python lacks a built-in mechanism for such checks. While `Lib/test` (the regression suite) exists, it is designed for **language developers** to verify correctness, not for **end-users** to verify environment integrity. Users facing “broken” environments (e.g., missing OpenSSL headers, corrupted paths, permission issues in Docker/Linux) currently have to debug ad-hoc. This proposal introduces a standardized “sanity check” similar to `rustup check`, `brew doctor`, or Neovim’s `:checkhealth`. **The Proposal** The module would expose a simple CLI entry point: `python -m do_check` It would perform **non-destructive verification** of: 1. **Critical C-extensions:** Ensuring `math`, `json`, `ctypes` are importable and functional. 2. **Permissions:** Checking write permissions in `CWD` and `Temp`. 3. **System Resources:** verifying availability of system entropy (`random`). 4. **External Libraries:** Verifying `ssl` context creation and `sqlite3` availability. If there are any type of questions regarding the Idea, then feel free to comment! ---
**Author:** ![bwoodsend](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/bwoodsend/32/4027_2.png) [@bwoodsend](https://discuss.python.org/u/bwoodsend)\ **Post date:** [December 1, 2025, 1:58pm UTC](https://discuss.python.org/t/standard-library-health-check-module/105153/2 "2025-12-01T13:58:11Z")
Bear in mind that most extension modules and the external libraries they depend on are optional and that limiting permissions is a normal, healthy security precaution. At best, you’d need a configurable health check that can be told either what kind of deployment Python is running under or what checks to ignore. ---
**Author:** ![Auberryy](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/auberryy/32/32909_2.png) [@Auberryy](https://discuss.python.org/u/Auberryy)\ **Post date:** [December 1, 2025, 2:03pm UTC](https://discuss.python.org/t/standard-library-health-check-module/105153/3 "2025-12-01T14:03:54Z")
That is a really good point regarding hardened environments and optional dependencies. I definitely agree that we shouldn’t flag a read-only container as “broken” when that is the intended security posture. Perhaps the solution is to treat the module as a **Capability Reporter** rather than a strict Pass/Fail test? Instead of exiting with an error, it could output a structured summary of what is and isn’t available. Or, as you suggested, we could support CLI flags/profiles to target the check: - `python -m healthcheck --strict` (for development machines) - `python -m healthcheck --minimal` (for containers/embedded) This way, it becomes a tool for auditing the environment rather than just validating it. Regarding the naming (`do_check` or `healthcheck`), I treated my suggestion simply as a placeholder. I am happy to defer the final naming decision to the Core Team/Community to ensure it fits Standard Library conventions. ---
**Author:** ![Nodd](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/nodd/32/6805_2.png) [@Nodd](https://discuss.python.org/u/Nodd)\ **Post date:** [December 1, 2025, 2:17pm UTC](https://discuss.python.org/t/standard-library-health-check-module/105153/4 "2025-12-01T14:17:07Z")
Could this be a pypi module, at least as a starting point ? If it doesn’t already exist, I didn’t check. ---
**Author:** ![Auberryy](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/auberryy/32/32909_2.png) [@Auberryy](https://discuss.python.org/u/Auberryy)\ **Post date:** [December 1, 2025, 2:29pm UTC](https://discuss.python.org/t/standard-library-health-check-module/105153/5 "2025-12-01T14:29:17Z")
I could certainly publish this as a PyPI module (and likely will as a prototype), but that runs into a critical ‘Bootstrap Paradox’: If a user’s environment is broken (e.g. SSL is missing, or ctypes is failing), `pip install` often fails as well. So a user effectively cannot install the tool to diagnose _why_ their installation is broken, because the installation process itself relies on a healthy environment. I believe this functionality belongs in the Standard Library because it acts as a ‘First Responder’, it needs to be available before external packages can be successfully installed. ---
**Author:** ![jamestwebber](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/jamestwebber/32/12799_2.png) [@jamestwebber](https://discuss.python.org/u/jamestwebber)\ **Post date:** [December 1, 2025, 2:33pm UTC](https://discuss.python.org/t/standard-library-health-check-module/105153/6 "2025-12-01T14:33:14Z")
> [@Auberryy](#): > > If a user’s environment is broken (e.g. SSL is missing, or ctypes is failing), `pip install` often fails as well. Perhaps this functionality belongs in [`ensurepip`](https://docs.python.org/3/library/ensurepip.html), then? ---
**Author:** ![Auberryy](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/auberryy/32/32909_2.png) [@Auberryy](https://discuss.python.org/u/Auberryy)\ **Post date:** [December 1, 2025, 2:40pm UTC](https://discuss.python.org/t/standard-library-health-check-module/105153/7 "2025-12-01T14:40:50Z")
It is an interesting location for it, specifically for the `pip` dependency checks. My main concern with `ensurepip` is availability and scope though. 1. On some popular distributions such as Debian or Ubuntu, `ensurepip` is often split out into a separate package so if the user has a minimal/broken install, `ensurepip` itself might be missing, rendering the tool inaccessible. 2. The vision of the tool is checking things unrelated to pip/packaging such as `sqlite3` availability, `math` precision, or basic file system permissions for the application itself. I feel like placing it in `ensurepip` might hide it from users who are debugging general runtime issues, not just installation issues. ---
**Author:** ![NeilGirdhar](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/neilgirdhar/32/5776_2.png) [@NeilGirdhar](https://discuss.python.org/u/NeilGirdhar)\ **Post date:** [December 1, 2025, 2:43pm UTC](https://discuss.python.org/t/standard-library-health-check-module/105153/8 "2025-12-01T14:43:54Z")
It should be a PyPI module to start anyway so that you can benefit from a quick release cycle. IMO, wait until you have a stable version, then submit a PEP to have it included. Not a bad idea IMO. You may also want to expose the health-check output (e.g., through a standard output format) so that programs that rely on Python (like NeoVim) can run the healthcheck and report the results to users. ---
**Author:** ![Auberryy](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/auberryy/32/32909_2.png) [@Auberryy](https://discuss.python.org/u/Auberryy)\ **Post date:** [December 1, 2025, 2:50pm UTC](https://discuss.python.org/t/standard-library-health-check-module/105153/9 "2025-12-01T14:50:06Z")
That is very sound advice. I agree that iterating on PyPI is the best way to refine the logic and catch edge cases without being tied to the slower Standard Library release cycle. I am currently still on the planning board to think about what comes in and what doesn’t come in. Regarding the output: The idea of a standard output format (likely JSON) for external tools like Neovim is excellent. I will definitely include a `--json` flag in the prototype to support that integration. My long-term goal remains the Standard Library (via a PEP, as you suggested) to address the ‘Bootstrap Paradox’ where `pip` itself is broken, but I will focus on stabilizing the feature set externally first. Thank you for the feedback! ---
**Author:** ![MegaIng](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/megaing/32/16162_2.png) [@MegaIng](https://discuss.python.org/u/MegaIng)\ **Post date:** [December 1, 2025, 2:52pm UTC](https://discuss.python.org/t/standard-library-health-check-module/105153/10 "2025-12-01T14:52:53Z")
> [@Auberryy](#): > > On some popular distributions such as Debian or Ubuntu, `ensurepip` is often split out into a separate package so if the user has a minimal/broken install, `ensurepip` itself might be missing, rendering the tool inaccessible. But those distros may also decide to not include the healthcheck module for the similar reasons they don’t include `ensurepip`. I would suggest you developed it as a single-file module that can be easily downloaded from some static url (similar to old `get-pip.py`). Then running it would just be two steps in the command line on any platform with any kind of internet access. ---
**Author:** ![Auberryy](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/auberryy/32/32909_2.png) [@Auberryy](https://discuss.python.org/u/Auberryy)\ **Post date:** [December 1, 2025, 2:59pm UTC](https://discuss.python.org/t/standard-library-health-check-module/105153/11 "2025-12-01T14:59:50Z")
That is a valid concern regarding the distribution policies, however I believe the distinction lies why certain things are often stripped. To my knowledge distributions typically remove some things is because it bundles binary wheels and encourages bypassing the system package manager. In contrast, my idea would be a lightweight, pure-Python diagnostic module with zero side effects. It doesn’t install any packages or modify the system, so there is little incentive for mantainers to strip it out (similar to how they don’t strip `unittest` or `logging`). Regarding the single-file download suggestion: That is a good fallback, but it relies on Network and SSL being functional. If for example a user is facing an SSL certificate issue (common in corporate /proxy enviroments) or is on an air-gapped machine, they cannot download the script. Having it in the standard library ensures the diagnostic tool is available even when the bridge to the outside world is down. ---
**Author:** ![mikeshardmind](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/mikeshardmind/32/14381_2.png) [@mikeshardmind](https://discuss.python.org/u/mikeshardmind)\ **Post date:** [December 1, 2025, 3:01pm UTC](https://discuss.python.org/t/standard-library-health-check-module/105153/12 "2025-12-01T15:01:55Z")
Personally, I’d rather see more things no longer be considered optional modules. It’s not like people actually defensively import for core functionality expected to be present, and it’s increasingly less reasonable over time that things like ssl support are absent on a system. ---
**Author:** ![jamestwebber](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/jamestwebber/32/12799_2.png) [@jamestwebber](https://discuss.python.org/u/jamestwebber)\ **Post date:** [December 1, 2025, 3:02pm UTC](https://discuss.python.org/t/standard-library-health-check-module/105153/13 "2025-12-01T15:02:18Z")
> [@Auberryy](#): > > If for example a user is facing an SSL certificate issue (common in corporate /proxy enviroments) or is on an air-gapped machine, they cannot download the script. Having it in the standard library ensures the diagnostic tool is available even when the bridge to the outside world is down. Perhaps that environment will deign to include your third-party script in their standard install? I don’t think it’s worth debating stdlib inclusion at this point–it’s too early. That debate can happen if/when there’s a real tool to discuss. ---
**Author:** ![Auberryy](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/auberryy/32/32909_2.png) [@Auberryy](https://discuss.python.org/u/Auberryy)\ **Post date:** [December 1, 2025, 3:06pm UTC](https://discuss.python.org/t/standard-library-health-check-module/105153/14 "2025-12-01T15:06:07Z")
That is a fair assessment. I agree that debating the distribution echanics is premature without a mature reference implementation to point to. I will follow the advice from you and Neil: I’ll focus on building out the PyPI package first. I’ll implement the JSON reporting and refine the “Capability Reporting” logic based on the feedback here Once the tool has proven its utility in the wild, I will return with data to discuss standard library includion. ---
**Author:** ![Auberryy](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/auberryy/32/32909_2.png) [@Auberryy](https://discuss.python.org/u/Auberryy)\ **Post date:** [December 1, 2025, 3:07pm UTC](https://discuss.python.org/t/standard-library-health-check-module/105153/15 "2025-12-01T15:07:17Z")
I completly agree. Ideally, the ecosystem would be strict enough that these chcks wouldn’t be necessary. But until we reach that state, I hope this tool can help users navigate the curent reality of “optional” modules. Thank you all for the initial feedback, it has been incredibly valuable! ---
**Author:** ![ZeroIntensity](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/zerointensity/32/10639_2.png) [@ZeroIntensity](https://discuss.python.org/u/ZeroIntensity)\ **Post date:** [December 1, 2025, 3:12pm UTC](https://discuss.python.org/t/standard-library-health-check-module/105153/16 "2025-12-01T15:12:26Z")
I like this idea. I’ve been burned several times by using a self-compiled CPython that has invalid state. Optional modules aside, something like this would be very helpful for issue triage, because we could automatically deduce some information like “is this on a system that PEP 11 supports?” or “is this on a security-only Python version?” If this were to be a PyPI package, I think this would be a lot less beneficial. You’d need pip to get the package, which requires a working interpreter! ---
**Author:** ![jamestwebber](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/jamestwebber/32/12799_2.png) [@jamestwebber](https://discuss.python.org/u/jamestwebber)\ **Post date:** [December 1, 2025, 3:20pm UTC](https://discuss.python.org/t/standard-library-health-check-module/105153/17 "2025-12-01T15:20:50Z")
> [@ZeroIntensity](#): > > If this were to be a PyPI package, I think this would be a lot less beneficial. You’d need pip to get the package, which requires a working interpreter! Perhaps a useful feature would be to check the health of a _different_ Python installation–so you could install from PyPI with a working version to check the health of a nonworking one. This doesn’t solve every use-case, but would help sometimes. I don’t think there’s _harm_ in releasing on PyPI. ---
**Author:** ![ZeroIntensity](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/zerointensity/32/10639_2.png) [@ZeroIntensity](https://discuss.python.org/u/ZeroIntensity)\ **Post date:** [December 1, 2025, 3:29pm UTC](https://discuss.python.org/t/standard-library-health-check-module/105153/18 "2025-12-01T15:29:08Z")
I’m not so sure that this should be a module at all. This makes much more sense as a CLI flag (e.g. `python --doctor`), because that won’t require invocation of the eval loop (which might be broken) to work. ---
**Author:** ![Auberryy](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/auberryy/32/32909_2.png) [@Auberryy](https://discuss.python.org/u/Auberryy)\ **Post date:** [December 1, 2025, 3:43pm UTC](https://discuss.python.org/t/standard-library-health-check-module/105153/19 "2025-12-01T15:43:12Z")
Thank you for validating the “Bootstrap Paradox”—that is exactly my fear with the PyPI-only route. ​regarding the implementation (-m healthcheck module vs --doctor flag): You are absolutely right that a module requires the import system to be functional, whereas a C-level flag (–doctor) could theoretically run even earlier in the startup sequence. ​I believe starting as a standard library module (written in Python) is the pragmatic “Step 1.” It solves 95% of cases (missing stdlib modules, broken paths, SSL issues) where the interpreter basically starts but is functionally crippled. ​Moving it to a C-level flag (–doctor) would be the ultimate robust solution, but perhaps that could be an optimization for later? ​Also, I love the point about **Issue Triage**. If users could just attach the output of python -m healthcheck --json to a GitHub issue, it would save maintainers so much time asking “What OS are you on? Do you have OpenSSL linked?” ---
**Author:** ![jamestwebber](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/jamestwebber/32/12799_2.png) [@jamestwebber](https://discuss.python.org/u/jamestwebber)\ **Post date:** [December 1, 2025, 3:47pm UTC](https://discuss.python.org/t/standard-library-health-check-module/105153/20 "2025-12-01T15:47:08Z")
Another benefit of a PyPI module (and/or a downloadable script) is that it can be backwards compatible, which allows Python \<= 3.14 to use it. A built-in version would be most useful, but will take the longest to become widespread. [Next page](https://discuss.python.org/t/standard-library-health-check-module/105153.md?page=2)