The PyPI Package Serves the immediate need, provides backwards compatibility for Python <= 3.14, and acts as a rapid-prototyping ground for new checks.
The Standard Library Module solves the fundamental “Bootstrap Paradox” for future versions.
You are right that a built-in version takes time to become widespread, but if we don’t plant the tree now (e.g., in 3.15), users five years from now will still face the same “broken pip, can’t install fix” deadlock.
I am committed to maintaining the PyPI version to bridge that gap as best as possible!
My primary concern is that a separate tool might have a very difficult time finding the relevant state used by the interpreter, but I’d like to see such a tool actually implemented to verify that concern.
The idea would be useful in general. And this addition could be valuable indeed.
When implementing, please ensure the JSON format doesn’t contain personal identifiable information or other confidential data. That can include paths (users/<name>), network, list of installed modules (other than stdlib and other more-or-less standard stuff, e.g. requests), etc.
That is a crucial privacy consideration, especially if we expect users to post these reports to public issue trackers.
Currently, the tool reports the specific path if a filesystem check fails. I will add a Sanitization Step to the roadmap for the next version (v0.1.2) to ensure user home directories and sensitive paths are masked (e.g., replaced with ~ or <REDACTED>) in the JSON output.
Status Update: I have just released the first alpha (v0.1.1) to Github to address the earlier feedback from Neil and Brénainn:
Added --json output.
Added graceful degradation for read-only filesystems.
In the Github Repository you can also find in the main directory the file called pycheck.py that is the full 1-file-module. If it causes confusion as that file can be used without the rest, then please feel free to mention it!
I will get to work on the PII sanitization for the next release. Thank you all again for the feedback and the tips, I appreciate it dearly!
It’s a nice use case, but does it really need new code or a package at all?
What more (or what less) does it need to do, than shallow clone the relevant branch of github.com/python/cpython and run the tests? The latter could even use unittest if the user really doesn’t want to install pytest.
That’s a far more complicated task for a novice trying to debug their installation, and doesn’t provide a succinct output. I don’t think it’s really comparable at all.
That is a very standard pattern for modern tooling (like poetry or rustup), and it works great for healthy systems.
However, for a diagnostic tool, I worry this introduces too many external dependencies:
One of the most common environment issues is missing or broken OpenSSL headers. While curl might successfully fetch the script, we are relying on the network stack being functional to diagnose why the network stack might be broken.
Many Enterprise/Defense environments cannot fetch external scripts. They need the diagnostic capability to be “batteries included” in the standard library to verify the integrity of an offline installation.
curl | python is not universally robust across all Windows versions or restricted containers.
I believe a health-check tool should be the “Fire Extinguisher”. It needs to be on the wall and ready to go before the fire starts, not ordered from somewhere while the house is burning.
@Auberryy Could you confirm if you are using LLM tools to write your messages? If so, a reminder that the Guidelines for this website explicitly forbid copy pasting LLM output, especially if you do not make this clear beforehand.
To be transparent, I have used LLMs to structure my arguments and polish my phrases, as I want to ensure that I am communicating clearly.
However, I want to be absoultely clear that this is all i use LLMs for as I am not an english native speaker.
I apologize greatly if it came over as if it was puerly generated by LLM, that was not my intend. The sole purpose for using LLM tools on my side was simpy to bring over the point of my view.
Thanks for the feedback! I have implemented the privacy and stability suggestions.
Changelog:
All file paths in the JSON output (--json) are now masked (e.g. ~ instead of /Users/Name). Note: I kept the human-readable output unmasked for local debugging purposes, but I will add sanitization there in v0.1.3.
Added test mocks to simulate broken SSL environments without needing to modify the host system.
Polished the PyPI page with proper badges and installation instructions (hence the bump to v0.1.2.post1).
I will try to make it compatible with more Python distribution, however that might take a bit because I want to firstly build out the Idea, so that everyone sees it.
Why was this thread moved to Python Help? This is a legitimate idea.
That, and I don’t think this script/tool should require invocation of the interpreter. If your installation is broken, running a health-check script will result in a fatal error, which isn’t exactly helpful.
This should be a C script that does not invoke the interpreter other than for diagnostic purposes. So, for example, if calling Py_Initialize will crash, it should catch that – but it should not require Py_Initialize to succeed in order to give sane output (which is not possible with a Python script).
Doing this in a third-party library is probably possible, but would be very difficult as it would require inspection of the runtime and debug offsets, which is no easy task unless your name is Pablo. We also couldn’t really use a third-party for triage.
You are absolutely right that a Python script relies on the interpreter successfully reaching Py_Initialize. If the runtime itself segfaults or the binary is corrupted, pycheck (as a module) will indeed fail to launch.
However, in my experience, the vast majority of “broken environments” are Configuration Mismatches (missing _ssl.so, broken sys.path, permission issues on site-packages) rather than binary corruption. A Python script is sufficient to diagnose these high-frequency issues.
I also chose Python specifically for Portability: A pure Python script can be installed temporarily via curl and run on any architecture (ARM, x86, RISC-V) without needing pre-compiled binaries. If this were a C extension or standalone binary, the distribution challenge would be massive compared to a simple script.
I don’t really agree (I find it’s more common that I have a broken interpreter, but that might be because I tend to work close to the core), but either way, there’s very little chance that a pure-Python script makes it into the standard library, so there’s not much point in discussing it. Remember, Python’s standard library is where code goes to die.
As others have stated, this seems straight out of ChatGPT. I don’t mind if you use LLMs to translate to English, but please don’t use them to argue for you. There’s just as much compatibility in a python --doctor flag, because in both cases, the bottom requirement is that there’s a compiled CPython binary available. It’s just that you could get a lot more information out of a --doctor flag and support more cases.
Stepping back a little bit, here’s what I’m envisioning:
$ python3 --doctor
Python 3.15.0 (main, Dec 4 2025, 00:00:00) [compiler yada yada]
security-only: no
system: Linux-6.1.0-35-amd64-x86_64-with
system supported by PEP 11: yes
missing modules: _ssl, _tkinter, ...
PYTHONHOME: intact
PYTHONPLATLIBDIR: intact
... list other potentially disruptive environment vars e.g. PYTHONTRACEMALLOC=1
pip available: yes
installed packages: requests, urllib3
initialization: OK
test script: OK
Something like this would provide way more information than what we currently ask for in our issue template, and I think it could save us a lot of time.
I appreciate the candor. To be clear on the LLM point: I use it strictly for translation and tone polishing as a non-native speaker. The frustration with sys.path issues and the desire for a portable fix are very much my own experiences. When it comed to your point regarding anything that enters the stdlib will die is accurate, however I also wish to help Python and the community as Python is just an awesome open-source language i really enjoy coding with.
Regarding C vs. Python: You are absolutely right that a C-level --doctor flag is the technically superior end-state, as it survives interpreter corruption. However, my C skills are not currently at a level where I could implement that safely in CPython.
Since I cannot write the C version right now, I will do the next best thing: I will update pycheck to match the exact output format you described above (checking PYTHONHOME, PEP 11 support, environment variables, etc.). This way, we can field-test the logic and see if that specific information actually helps with triage.
I will get to work on this for the next update, though please give me some time to implement it correctly.
Thank you for the detailed blueprint!
I previously stated that I’d want fewer things built as optional modules going forward. While I still stand by that, I really appreciate the example here of what other gains would be had from implementing this in Python, and am much more in favor of such after seeing the argument laid out.
A few other things I’ve seen be “broken” that I’d list here while it’s being considered:
which optional hashlib functions are available
location, version, and configuration of openssl
issues with Rosetta on OSX and non-native Python arch, since libraries loaded won’t be wrapped by Rosetta (can we detect this reliably from where this would exist?)