Install & Compatibility
Where this runs
tested against v0.25.1.6 · 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
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 18.1MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.6s · import 0.000s · 19MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
AudioSegment
✓ from pydub_stubs import AudioSegment
✗ from pydub import AudioSegment
This quickstart demonstrates basic pydub functionality: loading an audio file, applying a simple effect (volume boost), and exporting the result. It uses a programmatically generated WAV file to ensure the example is runnable without external downloads. For handling common formats like MP3, FLAC, or OGG, ensure `ffmpeg` or `libav` is installed and accessible in your system's PATH.
from pydub import AudioSegment
from pydub.playback import play
import os
# Create a dummy silent WAV file for demonstration
silent_audio = AudioSegment.silent(duration=1000) # 1 second of silence
silent_audio.export("input.wav", format="wav")
# Load an audio file (replace with your actual file if not using dummy)
song = AudioSegment.from_file("input.wav", format="wav")
# Boost volume by 6 dB
louder_song = song + 6
# Export the modified audio
louder_song.export("output.wav", format="wav")
# Play the original and louder song (requires simpleaudio or similar for playback)
# print("Playing original song...")
# play(song)
# print("Playing louder song...")
# play(louder_song)
print("Original and louder audio files created as input.wav and output.wav")
print("Note: For non-WAV formats (like MP3), pydub requires ffmpeg or libav to be installed and in your system PATH.")
# Clean up dummy files
os.remove("input.wav")
os.remove("output.wav")
Debug
Known issues
gotchapydub requires external (non-Python) dependencies like FFmpeg or libav for processing most audio formats (e.g., MP3, FLAC, OGG). Without them, it can only handle WAV files. These must be installed separately and made available in your system's PATH.fixInstall FFmpeg or libav from their official sources and add their binary directory to your system's PATH environment variable.
affects: All pydub versions
gotchaSome pydub functions, especially certain effects, are dynamically added to the `AudioSegment` class at runtime. While `pydub-stubs` attempts to type these using overloads, some dynamically added methods might not be perfectly typed or accessible via direct import from submodules like `pydub.effects` if your type checker expects them on `AudioSegment` directly.fixRefer to the pydub documentation for the canonical way to use such functions. If type checking fails, consider using `# type: ignore` for specific lines or checking `pydub.effects` directly for the function if it's not present on `AudioSegment`.
affects: All pydub-stubs versions
deprecatedThe underlying `pydub` library utilizes standard library modules like `audioop`, which are slated for deprecation in Python 3.13. This may lead to deprecation warnings when using `pydub` (and implicitly, `pydub-stubs`) with newer Python versions.fixMonitor the pydub and pydub-stubs GitHub repositories for updates that address Python 3.13 compatibility. There might be alternative 'audioop-lts' packages or similar solutions emerging.
affects: pydub-stubs <= 0.25.1.6 (and corresponding pydub versions)
gotchaVersion numbers for stub packages like `pydub-stubs` are often structured (e.g., `major.minor.patch.stubs_version`). The `major.minor.patch` parts correspond to the version of the runtime package (`pydub`) they target. Discrepancies between the installed `pydub` version and the `pydub-stubs` version can lead to incorrect type hints or type checking failures.fixEnsure that the `pydub-stubs` version you install is compatible with your installed `pydub` version. It's often best to pin the `pydub-stubs` version to match your `pydub` version's major and minor components if issues arise.
affects: All pydub-stubs versions
gotchapydub frequently uses temporary files for conversions and intermediate processing. Users may encounter `FileNotFoundError` or `PermissionError` if the Python process lacks write permissions in the default temporary directory or the specified output directory.fixEnsure the user running the script has appropriate read/write permissions for the temporary directory (often specified by `TMPDIR` or `TEMP` environment variables) and any output directories. On Windows, this can sometimes be resolved by adjusting folder permissions or running as administrator. Setting the `TMPDIR` environment variable to a writable path can also help.
affects: All pydub versions
Upgrade
Version history
0.25.1.6latest on PyPI · released Apr 11, 2025
Audit
Dependencies
pydubrequiredThis package provides type information for the pydub library, which must be installed for runtime functionality.
ffmpegoptionalRequired by pydub for handling non-WAV audio formats (e.g., MP3, FLAC) and many audio operations. This is a system-level dependency, not a Python package.