librosa + NumPy 2: works; the real error is pkg_resources (tested)

librosa works with NumPy 2: 0.11.0 and 0.10.2.post1 ran load, STFT, MFCC, resample and pYIN on numpy 2.4.6 without warnings. librosa 0.10.1 and older break with ModuleNotFoundError: No module named 'pkg_resources', which comes from setuptools 82, not NumPy. Upgrade librosa or install setuptools<81.

1. librosa 0.11.0 on NumPy 2.4: works

Fresh pip install librosa==0.11.0 on Python 3.11 pulled numpy 2.4.6, numba 0.68.0 and scipy 1.17.1. This script writes a 2-second 440 Hz tone and runs load, STFT, MFCC, resample and pYIN pitch tracking:

import numpy as np, soundfile as sf
import librosa
print("librosa", librosa.__version__, "| numpy", np.__version__)
sr = 22050
t = np.arange(sr * 2) / sr
sf.write("tone.wav", 0.5 * np.sin(2 * np.pi * 440 * t), sr)
steps = [
    ("load", lambda: librosa.load("tone.wav", sr=None)[0].shape),
    ("stft", lambda: np.abs(librosa.stft(y)).shape),
    ("mfcc", lambda: librosa.feature.mfcc(y=y, sr=sr).shape),
    ("resample", lambda: librosa.resample(y, orig_sr=sr, target_sr=16000).shape),
    ("pyin", lambda: float(np.nanmedian(librosa.pyin(y, fmin=100, fmax=1000, sr=sr)[0]))),
]
y = None
for name, f in steps:
    try:
        r = f()
        if name == "load": y = librosa.load("tone.wav", sr=None)[0]
        print(name, "->", r)
    except Exception as e:
        print(name, "->", type(e).__name__ + ":", str(e).splitlines()[0][:200])

librosa 0.11.0 | numpy 2.4.6
load -> (44100,)
stft -> (1025, 87)
mfcc -> (20, 87)
resample -> (32000,)
pyin -> 441.27152886549857

No errors and no NumPy warnings. librosa itself is pure Python, so it has no compiled extension to break when NumPy goes from 1.x to 2.x. In the same test, 0.10.2.post1 gave identical numbers. (librosa 1.0.0 needs Python 3.12+ and numpy>=2.1.0.)

2. librosa 0.10.1 and older: No module named 'pkg_resources'

librosa 0.10.1 also installed next to numpy 2.4.6, and import librosa worked. The first real call failed:

import librosa
print("import ok:", librosa.__version__)
y, sr = librosa.load("tone.wav", sr=None)

import ok: 0.10.1
Traceback (most recent call last):
  File "b2.py", line 3, in <module>
    y, sr = librosa.load("tone.wav", sr=None)
[... importlib frames trimmed ...]
    from .convert import frames_to_samples, time_to_samples
  File "site-packages/librosa/core/convert.py", line 7, in <module>
    from . import notation
  File "site-packages/librosa/core/notation.py", line 8, in <module>
    from .intervals import INTERVALS
  File "site-packages/librosa/core/intervals.py", line 8, in <module>
    from pkg_resources import resource_filename
ModuleNotFoundError: No module named 'pkg_resources'

librosa 0.10.x loads submodules lazily, so the error appears at your first librosa.load/stft/feature call, not at import. librosa/core/intervals.py does from pkg_resources import resource_filename. pkg_resources comes from setuptools, and setuptools 82.0.0 removed it (81.0.0 still has it; tested). Fresh uv venvs and Python 3.12+ venvs have no setuptools at all, so it fails there too. librosa 0.9.2 fails the same way, already at import librosa.

3. Fixes

• Upgrade librosa to 0.10.2.post1 or later (0.11.0 above). Neither tested venv had setuptools installed, and both ran the full script.
• Or keep 0.10.1 and pip install "setuptools<81" (installed 80.10.2). Same script, same numbers, plus a deprecation warning:

librosa 0.10.1 | numpy 2.4.6
site-packages/librosa/core/intervals.py:8: UserWarning: pkg_resources is deprecated as an API. See https://setuptools.pypa.io/en/latest/pkg_resources.html. The pkg_resources package is slated for removal as early as 2025-11-30. Refrain from using this package or pin to Setuptools<81.
  from pkg_resources import resource_filename
load -> (44100,)
stft -> (1025, 87)
mfcc -> (20, 87)
resample -> (32000,)
pyin -> 441.27152886549857

Pinning numpy does not help here: the failure was never NumPy. librosa 0.9.2 with setuptools<81 also ran the script on numpy 2.4.6.

4. When it really is NumPy: numba

librosa depends on numba, and numba caps NumPy. If an older numba is pinned in your environment, upgrading NumPy breaks import librosa with ImportError: Numba needs NumPy 2.2 or less (or 2.0, 2.3...). Fix: upgrade numba or pin numpy below its cap. Tested caps per numba version: numba needs NumPy 2.x or less. Other libraries: NumPy 2 breaking changes.

Written with AI assistance. Measured on 2026-10-24 on Linux with Python 3.11.17 in fresh uv venvs: librosa 0.9.2, 0.10.1, 0.10.2.post1 and 0.11.0, numpy 2.4.6, numba 0.68.0, scipy 1.17.1, setuptools 80.10.2/81.0.0/82.0.0/84.2.1. Scripts ran verbatim; output pasted unedited except shortened paths and marked trims. PlainTables is our extension; librosa is free.