Install & Compatibility
Where this runs
tested against v0.25.1 · 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.95 runs
installs and imports cleanly · install 0.0s · import 0.052s · 18MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.6s · import 0.046s · 19MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
AudioSegment
✓ from pydub import AudioSegment
AudioSegment is the primary class for representing and manipulating audio data.
This quickstart demonstrates how to load an audio file, apply common manipulations like changing volume and adding fade effects, and then export the result to a new file. It includes a fallback to create a dummy WAV file if no input is present, highlighting the dependency on FFmpeg for most real-world formats like MP3.
from pydub import AudioSegment
# Create a dummy audio file for the example (replace with your actual file)
# This part requires ffmpeg if you want to export to mp3/other formats.
# For pure WAV, pydub can handle it natively.
try:
# Attempt to create a simple silent WAV file if no external file exists
one_second_of_silence = AudioSegment.silent(duration=1000)
one_second_of_silence.export("input.wav", format="wav")
print("Created a dummy 'input.wav' file.")
except Exception as e:
print(f"Could not create dummy WAV: {e}. Please provide an existing audio file or ensure ffmpeg is installed for non-WAV formats.")
# --- Pydub operations ---
# Load an audio file (e.g., input.wav or input.mp3)
# If you use .mp3, make sure ffmpeg is installed and in your PATH.
try:
song = AudioSegment.from_file("input.wav", format="wav")
print(f"Loaded audio segment. Duration: {len(song) / 1000.0} seconds.")
# Increase volume by 6 dB
louder_song = song + 6
# Add a 2-second fade in and 3-second fade out
faded_song = louder_song.fade_in(2000).fade_out(3000)
# Export the manipulated audio to a new file
output_filename = "output.mp3"
faded_song.export(output_filename, format="mp3")
print(f"Exported '{output_filename}' successfully.")
# To play the audio (requires simpleaudio or pyaudio, and ffplay/avplay if not using WAV)
# from pydub.playback import play
# play(faded_song)
except FileNotFoundError:
print("Error: input.wav not found. Please create one or provide an existing audio file.")
except Exception as e:
print(f"An error occurred during audio processing: {e}. Check FFmpeg installation if using non-WAV files.")
Debug
Known issues
breakingPydub relies heavily on the external command-line tool FFmpeg (or Libav) for handling most audio formats (e.g., MP3, FLAC, OGG, AAC, MP4). Without FFmpeg/Libav installed on your system and its executable directory added to your system's PATH environment variable, Pydub will only be able to process WAV and raw audio files.fixInstall FFmpeg or Libav for your operating system and ensure its `bin` directory is added to your system's PATH. For Windows, you may need to explicitly set `pydub.AudioSegment.converter = '/path/to/ffmpeg.exe'` or `pydub.AudioSegment.ffmpeg = '/path/to/ffmpeg'` if PATH setup is problematic.
affects: All versions
gotchaAudioSegment objects in Pydub are immutable. Operations like slicing, changing volume, or applying effects (`+`, `-`, `fade_in()`, `fade_out()`) return a *new* AudioSegment object. The original object remains unchanged.fixAlways assign the result of an operation to a new variable or reassign it to the original variable, e.g., `song = song + 6` rather than expecting `song` to be modified in-place.
affects: All versions
gotchaDirect audio playback from Pydub requires additional Python dependencies (like `simpleaudio` or `pyaudio`) or the `ffplay`/`avplay` executable (usually bundled with `ffmpeg`/`libav`) to be installed and accessible.fixFor playback, install `pip install simpleaudio` (recommended) or `pip install pyaudio`. Alternatively, ensure `ffplay` or `avplay` is available in your system PATH as part of your `ffmpeg`/`libav` installation.
affects: All versions
gotchaWhen issues arise, especially with converting between formats, the problem is often related to how Pydub interacts with FFmpeg/Libav via subprocess calls.fixTo debug, enable Pydub's converter logger:
```python
import logging
l = logging.getLogger("pydub.converter")
l.setLevel(logging.DEBUG)
l.addHandler(logging.StreamHandler())
# Now run your pydub code
```
This will print the exact FFmpeg commands Pydub is executing, helping you identify issues. affects: All versions
gotchaOn Windows, setting the system PATH for FFmpeg can sometimes be tricky or not fully recognized by Python environments.fixIf adding FFmpeg to PATH doesn't work, you can explicitly tell Pydub where to find the FFmpeg executable by setting `pydub.AudioSegment.converter` or `pydub.AudioSegment.ffmpeg` (depending on Pydub version and context) to the full path of the `ffmpeg.exe` file. Use double backslashes in Windows paths (e.g., `AudioSegment.converter = 'C:\ffmpeg\bin\ffmpeg.exe'`).
affects: All versions on Windows
breakingPydub internally attempts to use `audioop` (a standard Python C extension module) or its pure-Python fallback `pyaudioop` for core audio processing. A `ModuleNotFoundError` for either indicates that a fundamental audio processing dependency is missing, preventing Pydub from importing. This often occurs in minimal Python environments (like `python:*-alpine`) where `audioop` might not be included or available by default.fix1. If `audioop` is missing and you are using a minimal Python environment (e.g., `python:*-alpine`), consider switching to a more complete Python base image (e.g., `python:3.13-slim` or `python:3.13`).
2. If `pyaudioop` is the specific module not found, ensure it is installed: `pip install pyaudioop`. Pydub uses this as a pure-Python fallback when `audioop` is unavailable.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'pydub'
The 'pydub' library has not been installed in your current Python environment, or your interpreter is not pointing to the environment where it's installed.
fixEnsure you have activated the correct Python virtual environment (if using one), then install pydub using pip: `pip install pydub`.
FileNotFoundError: [WinError 2] The system cannot find the file specified: 'ffmpeg' (or 'ffprobe') / OSError: [Errno 2] No such file or directory: 'ffmpeg'
Pydub is a high-level wrapper and requires the external FFmpeg or Libav executables (specifically `ffmpeg` and `ffprobe`) to be installed and accessible in your system's PATH, or their paths explicitly set in your code.
fix1. Download FFmpeg binaries for your operating system (e.g., from `ffmpeg.org`).
2. Extract the downloaded files and add the path to the `bin` directory (containing `ffmpeg.exe` and `ffprobe.exe`) to your system's environment variables (PATH).
3. Alternatively, you can explicitly tell pydub where to find FFmpeg by setting `pydub.AudioSegment.converter` and `pydub.AudioSegment.ffmpeg` (or `pydub.AudioSegment.ffprobe`) in your Python script before using pydub, e.g., `from pydub import AudioSegment; AudioSegment.converter = '/path/to/ffmpeg.exe'`.
PermissionError: [Errno 13] Permission denied
This error occurs when pydub attempts to write an audio file to a directory where the Python process lacks the necessary write permissions, or when trying to access a temporary file that is locked.
fix1. Ensure the target directory for exporting audio files exists and that your script has write permissions to it.
2. Try exporting to a different, easily accessible directory (e.g., your user's Desktop or a dedicated `temp` folder).
3. If on Windows, try running your IDE or script as an administrator.
Decoding failed. ffmpeg returned error code: 1 (or 'Automatic encoder selection failed for output stream #0:0. Default encoder for format mp3 is probably disabled.')
These errors typically indicate an issue with FFmpeg's ability to process the input audio file (e.g., it's corrupted, an unsupported format, or missing necessary codecs in the FFmpeg build) or that FFmpeg cannot encode to the desired output format.
fix1. Verify the integrity and format of your input audio file. Try playing it with a media player.
2. Ensure your FFmpeg installation is complete and includes the necessary encoders/decoders for the formats you are working with (e.g., `libmp3lame` for MP3 encoding). Sometimes, downloading a 'full' or 'shared' build of FFmpeg can resolve missing codec issues.
TypeError: expected str, bytes or os.PathLike object, not int (when calling AudioSegment.export())
The `bitrate` parameter in the `AudioSegment.export()` method expects a string (e.g., '192k'), but an integer value was passed, which is incompatible with the underlying `subprocess` call to FFmpeg.
fixConvert the bitrate value to a string before passing it to the `export()` method. For example, change `sound.export(..., bitrate=192)` to `sound.export(..., bitrate='192k')` or `f'{bitrate}k'` if `bitrate` is an integer variable. Upgrade
Version history
0.25.1latest on PyPI · released Mar 10, 2021
Audit
Dependencies
ffmpeg / libavrequiredExternal system dependency required for processing most audio formats (MP3, FLAC, OGG, etc.). WAV files work without it. Must be installed separately and available in system PATH.
simpleaudiooptionalOptional Python library for audio playback functionality.
pyaudiooptionalOptional Python library for audio playback functionality (alternative to simpleaudio).
scipyoptionalOptional Python library for advanced audio filters and effects.