Bottleneck

1.6.0 · active · verified Sat Apr 11

Bottleneck is a Python library that provides a collection of fast, C-optimized functions for NumPy arrays, particularly useful for operations involving NaNs (Not a Number). It aims to offer significant performance improvements over equivalent NumPy functions for large arrays by implementing them in C. The current version is 1.6.0, with releases generally following significant NumPy updates or critical bug fixes, ensuring compatibility and performance.

Common errors

```
ModuleNotFoundError: No module named 'bottleneck'
```
cause The 'bottleneck' library is either not installed in your current Python environment or there is a typo in the import statement (e.g., incorrect capitalization).

fix Ensure 'bottleneck' is installed using pip: `pip install bottleneck`.
```
ERROR: Failed building wheel for bottleneck
```
cause This error occurs during installation when pip attempts to compile Bottleneck's C extensions but essential build tools (like Microsoft Visual C++ Build Tools on Windows or Xcode Command Line Tools on macOS) are missing or outdated, or pip/setuptools are old.

fix Install the required build tools for your OS (e.g., `xcode-select --install` on macOS, Visual C++ Build Tools for Python on Windows) and upgrade pip and setuptools: `pip install --upgrade pip setuptools`. If using Anaconda, `conda install bottleneck` is often more robust.
```
AttributeError: module 'bottleneck' has no attribute 'nanmean'
```
cause This typically indicates an older version of 'bottleneck' is installed that lacks the specific function being called (e.g., 'nanmean'), or there's an incompatibility with the installed NumPy version.

fix Upgrade 'bottleneck' to the latest version (`pip install --upgrade bottleneck`) and ensure your NumPy version is compatible. Sometimes, reinstalling 'bottleneck' after updating NumPy helps.
```
ImportError: Can't determine version for bottleneck
```
cause This error often arises when another library (commonly pandas) tries to import 'bottleneck' but fails to retrieve its version, possibly due to a file named `bottleneck.py` shadowing the actual library in your working directory, or a corrupted 'bottleneck' installation.

fix First, check for and remove any local `bottleneck.py` files that might be causing a naming conflict. Then, uninstall and reinstall 'bottleneck' and 'pandas': `pip uninstall bottleneck pandas && pip install bottleneck pandas` (or use `conda` equivalents).
```
ImportError: numpy.core.multiarray failed to import
```
cause This specific error occurs when 'bottleneck' (especially older versions like 1.3.8 or earlier) is imported with NumPy 2.0.0 or newer. It's due to a significant change in NumPy's C Application Binary Interface (ABI) which breaks compatibility with extensions compiled against older NumPy versions.

fix Upgrade 'bottleneck' to version 1.4.0 or newer, which provides compatibility with NumPy 2.0.0: `pip install --upgrade bottleneck`.

Warnings

gotcha Results from bottleneck functions might differ slightly from NumPy equivalents due to distinct algorithms and floating-point arithmetic. This is generally within acceptable numerical precision but could be a concern for highly sensitive applications.
Fix: Always test `bottleneck` functions against `numpy` for critical numerical precision requirements to ensure the minor differences are acceptable for your application.
gotcha Performance gains from bottleneck are primarily noticeable for large arrays and specific operations (especially those handling NaNs). For small arrays, the overhead of calling the C extension might negate or even reverse performance benefits compared to pure NumPy.
Fix: Profile your code with both `bottleneck` and `numpy` for your specific array sizes and operations to confirm `bottleneck` provides a benefit in your use case.
breaking Bottleneck 1.x series (including 1.6.0) requires Python 3.10 or newer. Installing on older Python versions will fail.
Fix: Ensure your Python environment is version 3.10 or newer. If you must use an older Python version, refer to bottleneck's historical documentation for compatible versions (e.g., 1.3.2 for Python 3.7+).

Install

pip install bottleneck Install stable release

Imports

bottleneck
```
import bottleneck as bn
```

Quickstart

This example demonstrates how to import bottleneck as 'bn' and use its NaN-aware functions, such as `nansum` and `nanmean`, on NumPy arrays for potentially faster computation.

import numpy as np
import bottleneck as bn

a = np.array([1.0, 2.0, np.nan, 4.0])
b = np.arange(12.0).reshape(3, 4)
b[0, 0] = np.nan

print(f"Original array a: {a}")
print(f"bn.nansum(a): {bn.nansum(a)}")

print(f"\nOriginal array b:\n{b}")
print(f"bn.nanmean(b, axis=1): {bn.nanmean(b, axis=1)}")

view raw JSON →