Critical Build Failures and Destructive Compilation Script in quantcrypt v1.0.1 on Linux (Python 3.13)

[ThunderD9]

I tried to run this in debain(docker - python:3.13-bookworm) and it failed, this is the error i am getting:

from quantcrypt.dss import MLDSA_87

dss = MLDSA_87()
Traceback (most recent call last):
File "/usr/local/lib/python3.13/site-packages/quantcrypt/internal/pqa/common.py", line 81, in init
self._lib = self._import(self.variant)
~~~~~~~~~~~~^^^^^^^^^^^^^^
File "/usr/local/lib/python3.13/site-packages/quantcrypt/internal/pqa/common.py", line 76, in _import
return importlib.import_module(module_path).lib
~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^
File "/usr/local/lib/python3.13/importlib/init.py", line 88, in import_module
return _bootstrap._gcd_import(name[level:], package, level)
~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "", line 1387, in _gcd_import
File "", line 1360, in _find_and_load
File "", line 1310, in _find_and_load_unlocked
File "", line 488, in _call_with_frames_removed
File "", line 1387, in _gcd_import
File "", line 1360, in _find_and_load
File "", line 1324, in _find_and_load_unlocked
ModuleNotFoundError: No module named 'quantcrypt.internal.bin'

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
File "", line 1, in
dss = MLDSA_87()
File "/usr/local/lib/python3.13/site-packages/pydantic/_internal/_validate_call.py", line 39, in wrapper_function
return wrapper(*args, **kwargs)
File "/usr/local/lib/python3.13/site-packages/pydantic/_internal/_validate_call.py", line 136, in call
res = self.pydantic_validator.validate_python(pydantic_core.ArgsKwargs(args, kwargs))
File "/usr/local/lib/python3.13/site-packages/quantcrypt/internal/pqa/dss_algos.py", line 81, in init
super().init(variant, allow_fallback)
~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^
File "/usr/local/lib/python3.13/site-packages/quantcrypt/internal/pqa/common.py", line 90, in init
raise errors.PQAImportError(self.spec, self.variant)
quantcrypt.internal.errors.PQAImportError: Failed to import clean binaries of the MLDSA_87 algorithm.

Description:

The quantcrypt library (v1.0.1) exhibits a series of critical issues when installed in a standard Linux environment (Debian Bookworm, Python 3.13), making it unusable without significant and undocumented workarounds. The installation process is misleading, the provided compilation tools are broken, and the primary build script is destructive to the Python environment.

Environment:

Library Version: quantcrypt==1.0.1
Operating System: Debian 12 "Bookworm" (via python:3.13-bookworm Docker image)
Python Version: 3.13.4
Installation Method: pip within a Docker build

Summary of Issues

Failure to Install Precompiled Binaries: Despite claims of shipping with precompiled binaries, pip install quantcrypt does not install them for Python 3.13 on Linux. This immediately causes a ModuleNotFoundError: No module named 'quantcrypt.internal.bin' at runtime.

Misleading [compiler] Extra: The documented pip install "quantcrypt[compiler]" command does not trigger a compilation of the native binaries. It only installs the qclib command-line tool. The build process is still skipped, leading to the same runtime error.

Unreachable Pure-Python Fallback: The allow_fallback=True parameter is ineffective. The library attempts to import quantcrypt.internal.bin before checking this flag, causing a PQAImportError and making the pure-Python implementation unreachable if binaries were never compiled.

Destructive Manual Compilation Script: The undocumented manual build step, qclib compile, is catastrophically broken. After execution, it deletes or corrupts the Python interpreter executable that was used to run it, making further python or pip commands fail with No such file or directory.

Chronological Investigation and Failed Solutions

This section details the logical progression of debugging steps undertaken to resolve the initial ModuleNotFoundError. Each step revealed a deeper issue with the library.

Attempt 1: Standard Installation
Action: pip install quantcrypt
Result: Installation succeeds, but fails at runtime with ModuleNotFoundError: No module named 'quantcrypt.internal.bin'.
Conclusion: Precompiled binaries are not available for this platform.

Attempt 2: Use [compiler] Extra (The Documented Method)
Action: Install build tools (build-essential, cmake, etc.) and run pip install "quantcrypt[compiler]".
Result: Build succeeds with no errors, but the runtime error persists.
Conclusion: The [compiler] extra does not trigger the C extension build as expected.

Attempt 3: Use the Pure-Python Fallback
Action: Instantiate with MLDSA_87(allow_fallback=True).
Result: The exact same PQAImportError occurs.
Conclusion: The fallback mechanism is broken and cannot be used to bypass the need for compiled binaries.

Attempt 4: Manual Compilation with qclib
Action: After installation, manually run qclib compile inside the container.
Result: The compile command reports ✔ - Operation successful!. However, subsequent attempts to run python or python3.13 in the same shell session fail with bash: /usr/local/bin/python: No such file or directory.
Conclusion: The qclib script is the correct way to trigger a build, but it is dangerously destructive to the Python environment it runs in.

Attempt 5: Force Correct Python Interpreter
Observation: The python:3.13-bookworm image contains both python3.13 and the system's python3.11. The qclib script appeared to be incorrectly using python3.11.
Action: Explicitly run the compilation with the correct interpreter: python3.13 $(which qclib) compile --no-ask.
Result: The compilation still reports success, but it still deletes the python3.13 executable, proving the script's destructive nature is tied to the interpreter that runs it.

[aabmets]

@ThunderD9 Where in the documentation it is said that QuantCrypt is supported in Docker images?
You sure sound quite angry for undocumented behavior of free software which I did not get paid for to build.
Instead of bitching about it, why don't you find out the root cause of the problem, fix it, and open a pull request against this repository?

[ThunderD9]

@aabmets My apologies if the tone of the report came across as frustrated. It was the result of a very long debugging session, and I absolutely appreciate the effort you've put into this open-source project.

You asked for a root cause analysis, and I was happy to provide one. The library works perfectly for me on my local Windows machine, so to understand why it was failing, I needed a reliable way to test it on Linux.

I used a Docker container for this, as it acts like a brand-new, clean Linux server every time This is a standard and effective way to prove that any issues are with the library's packaging for Linux, not a user's specific machine configuration. This clean-room testing method allowed me to uncover the following core issues in the build and distribution pipeline for Linux:

To help with a potential fix or PR, here is the summary of the root causes our investigation uncovered. These are separate, distinct problems:

1. Root Cause: PyPI Source Package is Incomplete.

Evidence: As shown in the final forensic build log, when a user on Linux does a fresh pip install quantcrypt, pip downloads the source package (sdist). This installed package is missing the compile subcommand in its qclib tool.
Impact: This makes it impossible for an end-user on Linux to compile the required binaries, as the necessary tool is not included in the PyPI distribution.

2. Root Cause: The [compiler] Extra is Non-Functional.

Evidence: Running pip install "quantcrypt[compiler]" does not trigger a compilation. It appears to be a no-op that doesn't execute the build script.
Impact: The documented method for building from source does not work.

3. Root Cause: The Build Script is Destructive.

Evidence: In an environment where the compile command is present (e.g., a local developer checkout), running it actively corrupts the environment by deleting or moving the Python executable that was used to call it. We confirmed this by running python3.13 $(which qclib) compile and then immediately seeing python3.13: No such file or directory.
Impact: The build tool cannot be safely used in any automated build pipeline (like a Dockerfile), as it breaks the environment for subsequent steps.

Path Forward

A pull request for this would be difficult for an outsider as it touches deep issues in the project's packaging (pyproject.toml/setup.py) and build scripting logic. However, the most effective solutions would be:

Publish manylinux Wheels: This would be the single biggest fix. It would provide Linux users with the same seamless, out-of-the-box experience that Windows users currently have, bypassing the entire broken build process.

Fix the sdist Packaging: Ensure that the qclib compile command is correctly included in the source package distributed on PyPI.

Fix the Destructive Script: The build script needs to be audited to find and fix the step that corrupts the Python installation.
I hope this detailed root cause analysis is more helpful and provides a clear, evidence-based path to resolving these issues for the Linux userbase. I'm happy to provide the full forensic build logs or the Dockerfile used if it helps in debugging.

Thanks again for your work on this project.

P.S. Re-opening this issue, as closing it would imply the problem is resolved. My goal is to save the next developer from losing time, debugging this. The detailed analysis here can serve as a valuable warning and guide for any other Linux users until a fix is available.

[aabmets]

@ThunderD9 I'm currently busy with my aes-blake project. I'll get around to fixing this when I'm done with that project, which could take months, as I also intend to write a hardware implementation of the cipher using the Lucid language for Alchitry boards. If you need the fix faster, you'll have to learn how QuantCrypt works and fix it yourself. BTW, QuantCrypt already provides manylinux wheels which are built in GitHub Actions. I tested QuantCrypt myself by running it on WSL Ubuntu 24.0, and all tests passed.

[ThunderD9]

@aabmets

You are correct that manylinux wheels exist on PyPI. The problem is that they are not portable to many standard Linux environments, including the python:3.13-bookworm (Debian 12) image.

The Root Cause:

The wheels are tagged as manylinux_2_39, meaning they require glibc version 2.39 or newer.
https://pypi.org/project/quantcrypt/1.0.1/#files

However, Debian 12 uses glibc 2.36. Because the system's glibc is older than the wheel's requirement, pip correctly determines the wheel is incompatible and is forced to fall back to the source distribution (.tar.gz).

This is why I encountered all the build failures. The entire investigation into the broken source package was only necessary because the provided wheels are not usable on a standard Debian system.

The Path to a Fix:

The solution would be to adjust the GitHub Actions CI pipeline to build the wheels against an older, more compatible manylinux standard, such as manylinux2014 (glibc 2.17) or manylinux_2_28 (glibc 2.28). This would produce truly portable wheels that would work out-of-the-box for nearly all Linux users, resolving the issue entirely.

I understand you are busy. This issue can remain here as a public record. Thank you for the discussion that ultimately led to this discovery.

[hk92292831]

@ThunderD9 I'm currently busy with my aes-blake project. I'll get around to fixing this when I'm done with that project, which could take months, as I also intend to write a hardware implementation of the cipher using the Lucid language for Alchitry boards. If you need the fix faster, you'll have to learn how QuantCrypt works and fix it yourself. BTW, QuantCrypt already provides manylinux wheels which are built in GitHub Actions. I tested QuantCrypt myself by running it on WSL Ubuntu 24.0, and all tests passed.

Hi, thank you very much for the great work and looking forward to seeing the updates. I also faced similar issues when porting from MsWindow to Linux.

[hk92292831]

Hi, thank you very much for the great work and looking forward to seeing the updates. I also faced similar issues when porting from MsWindow to Linux.

[ZM-J]

I have encountered the same issue here. Both FROM python:3-slim and FROM python:3-slim-bullseye failed.

After executing RUN qclib compile -N, the script deleted all files in /usr/local/bin, which corroborates statements from @ThunderD9 .

For pip installation in docker, the shared objects should be placed in /usr/local/lib/python3.14/site-packages/quantcrypt/internal/bin. However, the current qclib compile would generate shared objects to /usr/local/bin. Therefore, I came up with the following expediency:

FROM python:3-slim
WORKDIR /app

RUN apt-get update
RUN apt-get install -y socat build-essential
RUN pip install pycryptodome quantcrypt[compiler]
RUN set -e \
    && mkdir -p /tmp/usr_local_bin_backup \
    && cp -a /usr/local/bin/. /tmp/usr_local_bin_backup/ \
    && QPATH=$(python3 -m pip show quantcrypt | grep '^Location:' | awk '{print $2}') \
    && qclib compile -N \
    # Move /usr/local/bin to quantcrypt/internal/bin
    && mkdir -p "$QPATH/quantcrypt/internal/bin" \
    && mv /usr/local/bin/* "$QPATH/quantcrypt/internal/bin/" \
    # Recover bin
    && cp -a /tmp/usr_local_bin_backup/. /usr/local/bin/ \
    && rm -rf /tmp/usr_local_bin_backup

This quick-fix looks somewhat stupid, but whatever, it works.