Install & Compatibility
Where this runs
tested against v0.3.2 · 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
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
features
✓ from nnAudio import features
STFT
✓ from nnAudio.features import STFT
✗ from nnAudio.Spectrogram import STFT
`nnAudio.Spectrogram` is being replaced by `nnAudio.features` as the primary module for spectrogram classes.
MelSpectrogram
✓ from nnAudio.features.mel import MelSpectrogram
This quickstart demonstrates how to create a dummy audio waveform, transfer it to the appropriate device (GPU if available), initialize an STFT layer using `nnAudio.features`, and generate a spectrogram. It highlights the typical workflow of using nnAudio as a PyTorch module.
import torch
import numpy as np
from nnAudio import features
# Simulate an audio waveform (e.g., from a .wav file)
sr = 16000 # Sample rate
duration = 1 # seconds
t = np.linspace(0, duration, int(sr * duration), endpoint=False)
# Simple sine wave at 440 Hz
song = 0.5 * np.sin(2 * np.pi * 440 * t, dtype=np.float32)
# nnAudio expects a batch dimension, so unsqueeze(0)
x = torch.tensor(song).unsqueeze(0)
# Move to GPU if available, otherwise CPU
device = 'cuda' if torch.cuda.is_available() else 'cpu'
x = x.to(device)
# Initialize a STFT spectrogram layer
# Pass sample rate (sr) to the layer
spec_layer = features.STFT(n_fft=2048, hop_length=512, sr=sr).to(device)
# Feed-forward your waveform to get the spectrogram
spectrogram = spec_layer(x)
print(f"Input waveform shape: {x.shape}")
print(f"Output spectrogram shape: {spectrogram.shape}")
print(f"Spectrogram layer on device: {next(iter(spec_layer.parameters())).device}")
nnaudio --version
Debug
Known issues
breakingThe `device` argument for initializing spectrogram layers (e.g., `STFT(device='cuda')`) was removed in version 0.2.0. Layers must now be moved to the desired device using the PyTorch standard `.to(device)` method after initialization.fixInitialize the layer without the `device` argument, then call `.to(device)`: `spec_layer = features.STFT(...).to(device)`.
affects: >=0.2.0
deprecatedThe `nnAudio.Spectrogram` module path is being replaced by `nnAudio.features`. While `nnAudio.Spectrogram` might still function, `nnAudio.features` is the recommended and future-proof import path for all spectrogram classes.fixUpdate import statements from `from nnAudio.Spectrogram import ...` to `from nnAudio.features import ...` (e.g., `from nnAudio.features import STFT`).
affects: >=0.3.1
gotchaFor full functionality, including the Griffin-Lim inverse transform, PyTorch version 1.6.0 or higher is required. Using older PyTorch versions might limit certain features.fixEnsure your PyTorch installation is `torch >= 1.6.0`.
affects: <1.6.0 (PyTorch)
gotchaWhile `librosa` is a common audio library, `nnAudio` is designed to function without it as a strict dependency. Necessary mel filter functions are included internally to prevent forced `librosa` installation issues.fixUsers can generally avoid installing `librosa` unless explicitly needed for other parts of their audio pipeline.
affects: All versions
Errors
Common errors & fixes
AttributeError: module 'numpy' has no attribute 'float'
The `nnAudio` library, particularly in older stable PyPI versions, uses `np.float`, which was deprecated in NumPy 1.20 and completely removed in NumPy 1.24. When used with newer NumPy versions, this results in an AttributeError.
fixDowngrade NumPy to a version prior to 1.24 (e.g., `pip install numpy==1.23.5`) or install `nnAudio` directly from its GitHub repository to get the latest fixes.
pip install nnAudio==0.3.x (errors creating CQT kernels)
Installing `nnAudio` via `pip install nnAudio` (for stable releases on PyPI) may lead to runtime errors, particularly when creating CQT kernels, because the PyPI package might be outdated or not include critical fixes present in the main GitHub branch.
fixInstall `nnAudio` directly from the GitHub repository to ensure you have the most up-to-date version with all recent fixes: `pip install git+https://github.com/KinWaiCheuk/nnAudio.git#subdirectory=Installation`.
from nnAudio.Spectrogram import ... (deprecated import)
The module path `nnAudio.Spectrogram` is deprecated and has been superseded by `nnAudio.features`. While the old path might still function, it is not the recommended or future-proof way to import spectrogram classes.
fixUpdate your import statements from `from nnAudio.Spectrogram import ...` to `from nnAudio.features import ...` (e.g., `from nnAudio.features import STFT`).
STFT(device='cuda') (device argument removed)
In `nnAudio` versions 0.2.0 and later, the `device` argument was removed from the initialization of spectrogram layers (like `STFT`, `CQT`). Layers must now be initialized without the device argument and then moved to the desired device using PyTorch's standard `.to(device)` method.
fixInitialize the spectrogram layer without the `device` argument, then move it to the target device: `spec_layer = features.STFT(...).to(device)`.
Upgrade
Version history
0.3.4latest on PyPI · released Dec 7, 2025
Audit
Dependencies
numpyrequiredFundamental for array operations.
scipyrequiredUsed for audio file I/O and signal processing utilities.
torchrequiredPrimary deep learning backend for GPU-accelerated operations.
librosaoptionalFunctionality like mel filters are internally duplicated; not a strict dependency but often used in audio workflows.