{"library":"numexpr","title":"Fast numerical expression evaluator for NumPy","description":"NumExpr is a Python library that provides a fast numerical expression evaluator for NumPy. It accelerates array operations by avoiding memory allocation for intermediate results, leading to better cache utilization and reduced memory access. It also leverages multi-threading to utilize multiple CPU cores and supports Intel's Math Kernel Library (MKL) for further performance gains, especially with transcendental functions. The current version is 2.14.1, and it maintains a regular release cadence.","status":"active","version":"2.14.1","language":"en","source_language":"en","source_url":"https://github.com/pydata/numexpr","tags":["numerical computing","numpy","performance","expression evaluation","multi-threading","jit"],"install":[{"cmd":"pip install numexpr","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Core dependency for array manipulation and data structures.","package":"numpy","optional":false},{"reason":"Optional dependency for enhanced performance, especially with transcendental functions on Intel architectures.","package":"mkl","optional":true}],"imports":[{"note":"Commonly imported as 'ne' for brevity, similar to 'np' for NumPy.","symbol":"numexpr","correct":"import numexpr as ne"},{"note":"The `evaluate` function is a direct method of the `numexpr` module, not a submodule.","wrong":"import numexpr.evaluate","symbol":"evaluate","correct":"ne.evaluate('expression')"}],"quickstart":{"code":"import numpy as np\nimport numexpr as ne\n\n# Create large arrays for demonstrating performance benefits\na = np.arange(1_000_000, dtype=np.float64)\nb = np.arange(1_000_000, 0, -1, dtype=np.float64)\n\n# Evaluate a complex expression using numexpr\nresult_ne = ne.evaluate(\"sin(a) + arcsinh(a/b) + (a * b - 4.1 * a) > 2.5 * b\")\n\nprint(result_ne)\nprint(f\"Result type: {result_ne.dtype}\")\n\n# You can also set the number of threads dynamically\n# print(f\"Current numexpr threads: {ne.nthreads}\")\n# ne.set_num_threads(4)\n# print(f\"New numexpr threads: {ne.nthreads}\")","lang":"python","description":"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."},"warnings":[{"fix":"Always 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.","message":"Breaking down expressions into multiple NumPy operations that create intermediate arrays negates NumExpr's primary performance and memory benefits.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Be 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.","message":"NumExpr'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).","severity":"gotcha","affected_versions":"All versions"},{"fix":"Set `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.","message":"Incorrectly 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Reserve `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.","message":"NumExpr introduces parsing and compilation overhead. For small arrays or very simple expressions, native NumPy operations can be faster due to this overhead.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Report 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.","message":"NumExpr 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.","severity":"breaking","affected_versions":"2.10.0 and later when used with NumPy 2.x"}],"env_vars":null,"last_verified":"2026-04-05T00:00:00.000Z","next_check":"2026-07-04T00:00:00.000Z"}