bottleneck

library1.6.0pypypi✓ verified 25d ago

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.

data

pip install bottleneck

github ↗package ↗

INSTALL

IMPORT

SIG · BOTTLENECK

bottleneck

datapythonv1.6.0

Install

3.8s avg

Import

260ms

Disk

91MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.6.0 · 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

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.258s · 90.6MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 3.8s · import 0.262s · 87MB

91MB installed

● package 91MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

bottleneck

✓ import bottleneck as bn

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)}")

Debug

Known issues

gotchaResults 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.

affects: All versions

gotchaPerformance 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.

affects: All versions

breakingBottleneck 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+).

affects: 1.4.0+

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'bottleneck'

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

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'

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

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

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`.

Upgrade

Version history

1.6.0latest on PyPI · released Sep 8, 2025

Audit

Dependencies

numpyrequiredCore functionality relies on NumPy arrays and C API for data structures and fundamental operations.

Agent activity

16 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/pydata/bottleneck ↗

packagehttps://pypi.org/project/bottleneck/ ↗