MyUCSpace

English

简体中文

English

简体中文

Appearance

NumPy And Python Compatibility Policy ​

The Django backend image uses Python 3.12 and pins NumPy in backend/requirements.txt:

text
numpy==1.26.4

This is a deployment compatibility decision, not a preference for older packages.

Why NumPy Stays On 1.26.4 ​

Some legacy servers and virtualized environments only support the baseline x86-64 instruction set and do not support x86-64-v2. NumPy 2.x Linux x86-64 wheels can require a higher CPU baseline, which may fail with illegal-instruction errors on those machines.

The NumPy CPU build documentation states that, on x86-64, the current default min baseline maps to X86_V2, and notes that this may not be compatible with pre-2009 CPUs or some older virtual machines. To avoid moving that risk into deployment, the backend stays on one of the final stable NumPy 1.x releases:

text
numpy==1.26.4

This keeps the backend on NumPy 1.x wheels that are compatible with older x86-64 environments and avoids the CPU-baseline risk introduced by NumPy 2.x.

References:

Why The Backend Uses Python 3.12 ​

The NumPy 1.26.4 release notes state that this version supports Python 3.9-3.12. Python 3.12 is therefore the highest Python version covered by official NumPy 1.26.4 wheels.

If the backend image moves to Python 3.13 or 3.14 while still pinning numpy==1.26.4, the package manager usually cannot use an official prebuilt wheel and falls back to a source build. Source builds add several risks:

  • Docker builds take significantly longer and need a more complete build environment.
  • Build output depends on the current compiler, system libraries, and CPU features, reducing deployment reproducibility.
  • A successful build may still reintroduce CPU instruction-set compatibility issues.
  • NumPy 1.26.4 does not declare support for Python 3.13 or 3.14, so runtime compatibility is not covered by upstream support.

For that reason, the Django backend image stays on:

dockerfile
FROM python:3.12-slim

This keeps both constraints true:

  • NumPy remains on 1.x for legacy servers that do not support x86-64-v2.
  • Python uses the highest version officially supported by NumPy 1.26.4, avoiding source builds and extra compatibility risk.

Maintenance Policy ​

While the project still supports servers without x86-64-v2:

  • Keep numpy==1.26.4 pinned instead of widening it to numpy>=....
  • Keep the Django backend Dockerfiles on Python 3.12 instead of Python 3.13 or newer.
  • Validate wheel availability, import behavior, core data-processing flows, and Docker build reproducibility on the target server CPU before upgrading NumPy or Python.

face-service also uses Python 3.12 and pins numpy==1.26.4 through constraints.txt. Because it depends on OpenCV, onnxruntime, and insightface, its upgrade risk is higher; it follows the same NumPy compatibility policy as the backend.