docs: document new libzstd version constraint behaviors

Closes #267.

Author: indygreg

c-ext/backend_c.c

@@ -138,7 +138,8 @@ void zstd_module_init(PyObject *m) {
     PyUnstable_Module_SetGIL(m, Py_MOD_GIL_NOT_USED);
 #endif
 
-    /* python-zstandard relies on unstable zstd C API features. This means
+    /*
+       python-zstandard relies on unstable zstd C API features. This means
        that changes in zstd may break expectations in python-zstandard.
 
        python-zstandard is distributed with a copy of the zstd sources.
@@ -152,19 +153,25 @@ void zstd_module_init(PyObject *m) {
 
        We detect this mismatch here and refuse to load the module if this
        scenario is detected.
+
+       Historically we required exact matches. But over the years the churn
+       in libzstd became reasonable and we relaxed this constraint to a minimum
+       version check. Our assumption going forward is that we will only rely on
+       unstable C API features that are in reality stable for years.
     */
     PyObject *features = NULL;
     PyObject *feature = NULL;
+    unsigned zstd_version_no = ZSTD_versionNumber();
     unsigned zstd_version_min = 10506;
     // if either compile-time or runtime version of libzstd is lower than expected, abort initialization
     if (ZSTD_VERSION_NUMBER < zstd_version_min ||
-        ZSTD_versionNumber() < zstd_version_min) {
+        zstd_version_no < zstd_version_min) {
         PyErr_Format(
             PyExc_ImportError,
             "zstd C API versions mismatch; Python bindings were not "
             "compiled/linked against expected zstd version (%u returned by the "
             "lib, %u hardcoded in zstd headers, %u hardcoded in the cext)",
-            ZSTD_versionNumber(), ZSTD_VERSION_NUMBER, zstd_version_min);
+            zstd_version_no, ZSTD_VERSION_NUMBER, zstd_version_min);
         return;
     }
 

docs/installing.rst

@@ -65,10 +65,6 @@ All Install Arguments
    Attempt to link against the zstd library present on the system instead
    of the version distributed with the extension.
 
-   The Python extension only supports linking against a specific version of
-   zstd. So if the system version differs from what is expected, a build
-   or runtime error will result.
-
 ``--warning-as-errors``
    Treat all compiler warnings as errors.
 
@@ -122,6 +118,11 @@ against. For best results, point this package at the exact same version of
 ``libzstd`` that it bundles. See the bundled ``zstd/zstd.h`` or
 ``zstd/zstd.c`` for which version that is.
 
+A build or run-time error can occur if the version of ``libzstd`` being built
+against does not exactly match our bundled version. Historically, we required
+an exact version match. But in September 2025 we relaxed this constraint to
+only require a minimum version match.
+
 When linking against an external ``libzstd``, not all package features may be
 available. Notably, the ``multi_compress_to_buffer()`` and
 ``multi_decompress_to_buffer()`` APIs are not available, as these rely on private

docs/news.rst

@@ -53,6 +53,8 @@ Version History
 * `setup.py` now depends on `packaging` and uses `packaging.version.Version` for
   version comparisons. This removes some deprecation warnings from usage of
   legacy distutils `Version` classes.
+* Relax run-time libzstd version checking in C extension from exactly 1.5.7
+  to >=1.5.6. (#254, #267)
 
 0.24.0 (released 2025-08-17)
 ============================