Install & Compatibility
Where this runs
tested against v2.14.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.278s · 94.4MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.7s · import 0.286s · 87MB
93MB installed
● package 93MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
numexpr
✓ import numexpr as ne
Commonly imported as 'ne' for brevity, similar to 'np' for NumPy.
evaluate
✓ ne.evaluate('expression')
✗ import numexpr.evaluate
The `evaluate` function is a direct method of the `numexpr` module, not a submodule.
This quickstart demonstrates how to import `numexpr` and use its primary `evaluate` function. It takes a string expression, which is then parsed and efficiently computed on large NumPy arrays, leveraging NumExpr's optimizations and multi-threading. The example uses common mathematical and logical operations.
import numpy as np
import numexpr as ne
# Create large arrays for demonstrating performance benefits
a = np.arange(1_000_000, dtype=np.float64)
b = np.arange(1_000_000, 0, -1, dtype=np.float64)
# Evaluate a complex expression using numexpr
result_ne = ne.evaluate("sin(a) + arcsinh(a/b) + (a * b - 4.1 * a) > 2.5 * b")
print(result_ne)
print(f"Result type: {result_ne.dtype}")
# You can also set the number of threads dynamically
# print(f"Current numexpr threads: {ne.nthreads}")
# ne.set_num_threads(4)
# print(f"New numexpr threads: {ne.nthreads}")
Debug
Known issues
gotchaBreaking down expressions into multiple NumPy operations that create intermediate arrays negates NumExpr's primary performance and memory benefits.fixAlways pass the entire complex expression as a single string to `numexpr.evaluate()` to allow the library to optimize the entire computation and avoid temporary memory allocations.
affects: All versions
gotchaNumExpr's internal casting rules and type promotion might differ slightly from NumPy's in specific cases (e.g., `int8`/`uint8` upcasting to `int32`, `uint32` to `int64`, and `abs()` on complex numbers returning a complex result).fixBe aware of potential type discrepancies for specific operations and explicitly cast arrays if exact NumPy-like type behavior is required. For example, use `real(abs(cplx))` for complex absolute values if a float result is expected.
affects: All versions
gotchaIncorrectly configuring threadpool settings (e.g., `NUMEXPR_MAX_THREADS`, `NUMEXPR_NUM_THREADS`, or `OMP_NUM_THREADS` environment variables) can lead to oversubscription and degraded performance, especially when combined with other parallel processing libraries or Python's threading.fixSet `NUMEXPR_MAX_THREADS` to a reasonable value, typically equal to or slightly less than the number of physical CPU cores. Adjust dynamic thread usage via `numexpr.set_num_threads()` if needed, and avoid oversubscribing when other parallel libraries are active.
affects: All versions
gotchaNumExpr introduces parsing and compilation overhead. For small arrays or very simple expressions, native NumPy operations can be faster due to this overhead.fixReserve `numexpr` for large arrays (typically larger than your CPU's L1 cache) and complex multi-operator expressions where its optimization benefits outweigh the overhead. Benchmarking is recommended for critical sections.
affects: All versions
breakingNumExpr 2.10.0 introduced *experimental* support for NumPy 2.0.0. While intended for forward compatibility, users adopting NumPy 2.x may encounter edge cases or instabilities.fixReport any issues encountered when using NumExpr with NumPy 2.x to the NumExpr GitHub repository. Consider pinning NumPy to a 1.x version if stability is critical and NumPy 2.x features are not strictly required.
affects: 2.10.0 and later when used with NumPy 2.x
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'numexpr'
The numexpr library is not installed in the Python environment you are currently using, or the environment is not correctly configured.
fixInstall numexpr using pip: `pip install numexpr` or `conda install numexpr` if you are using Anaconda/Miniconda.
ImportError: DLL load failed: The specified module could not be found.
This error, particularly on Windows, often means that a required C runtime library (like Microsoft Visual C++ Redistributable) or a dependency like Intel MKL is missing or cannot be found by numexpr.
fixEnsure you have the correct Microsoft Visual C++ Build Tools installed for your Python version (check Python's official documentation for compatible versions). If using MKL, consider installing numexpr via `conda` which often includes MKL support, or explicitly install `numpy+mkl` before numexpr.
KeyError: 'a' (when using numexpr.evaluate)
This occurs when a variable referenced in the expression string passed to `numexpr.evaluate` is not found in the local or global dictionaries provided, or if the `local_dict` and `global_dict` parameters are not explicitly passed.
fixPass the variables as `local_dict` or `global_dict` to `numexpr.evaluate`. For example, `ne.evaluate('a + b', local_dict={'a': a_array, 'b': b_array})` or `ne.evaluate('a + b', global_dict=globals())`. Failed Building wheel for numexpr
This error typically indicates that your system lacks the necessary C compiler (like GCC on Linux/macOS or MSVC Build Tools on Windows) to compile numexpr from source during installation when a pre-built wheel is not available.
fixInstall a compatible C compiler for your operating system (e.g., `sudo apt-get install build-essential` on Debian/Ubuntu, Xcode Command Line Tools on macOS, or Microsoft Visual C++ Build Tools on Windows). Alternatively, ensure you are using a Python version and platform for which pre-built numexpr wheels are available, or install via `conda` if possible.
Upgrade
Version history
2.14.2latest on PyPI · released Jul 18, 2026
Audit
Dependencies
numpyrequiredCore dependency for array manipulation and data structures.
mkloptionalOptional dependency for enhanced performance, especially with transcendental functions on Intel architectures.