Install & Compatibility
Where this runs
tested against v4.1.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
py 3.12
✕ dependency_conflict
✓ 70.9s
py 3.13
✕ no_wheel
✓ 68.45s
5734MB installed
● package 5734MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Separator
✓ import demucs.separator
✗ from demucs import Separator
This quickstart demonstrates how to use the `demucs.api.Separator` class to load an audio file (using a dummy file here) and separate it into its constituent stems (vocals, drums, bass, other). It then saves each separated stem as a WAV file in a specified output directory. Ensure `soundfile` and `numpy` are installed for the dummy audio generation if you don't use your own file.
import demucs.api
import os
# Create a dummy audio file for demonstration
dummy_audio_path = "test_audio.wav"
# This requires soundfile and numpy. In a real scenario, you would load an actual audio file.
try:
import numpy as np
import soundfile as sf
samplerate = 44100 # Hz
duration = 5 # seconds
frequency = 440 # Hz (A4 note)
t = np.linspace(0., duration, int(samplerate * duration), endpoint=False)
data = 0.5 * np.sin(2 * np.pi * frequency * t)
sf.write(dummy_audio_path, data, samplerate)
print(f"Created dummy audio file: {dummy_audio_path}")
# Initialize the separator. Uses the default 'htdemucs' model.
# You can specify other models: 'htdemucs_ft', 'mdx_extra', 'mdx_extra_q'
separator = demucs.api.Separator()
print(f"Separating audio file: {dummy_audio_path}")
# Separate the audio file
# The 'separated' variable will contain a dictionary where keys are stem names
# and values are the separated audio tensors (e.g., 'vocals', 'drums', 'bass', 'other')
origin, separated_stems = separator.separate_audio_file(dummy_audio_path)
# Save the separated stems
output_dir = "separated_stems"
os.makedirs(output_dir, exist_ok=True)
for stem_name, stem_audio in separated_stems.items():
output_path = os.path.join(output_dir, f"{os.path.basename(dummy_audio_path).replace('.wav', '')}_{stem_name}.wav")
demucs.api.save_audio(stem_audio, output_path, samplerate=separator.samplerate)
print(f"Saved {stem_name} to {output_path}")
finally:
# Clean up dummy file
if os.path.exists(dummy_audio_path):
os.remove(dummy_audio_path)
# Note: 'separated_stems' directory is left for inspection.
print(f"Cleaned up dummy audio file: {dummy_audio_path}")
demucs --version
Debug
Known issues
breakingDemucs v4.0.1 and later require Python 3.8 or higher. Python 3.7 is no longer supported.fixUpgrade your Python environment to 3.8 or later.
affects: >=4.0.1
breakingMajor architectural changes in Demucs v4 introduce breaking changes. Users updating from v3 might need to reinstall the library from scratch due to altered dependencies and internal structures.fixPerform a clean reinstallation (`pip uninstall demucs && pip install demucs`). Review your code for deprecated API calls; prefer `demucs.api.Separator` for programmatic use.
affects: 4.x.x from 3.x.x
gotchaUsers often encounter 'CUDA out of memory' errors when processing long audio files on GPUs, especially with high sample rates or default settings.fixReduce the segment size by using the `--segment` flag (e.g., `demucs --segment 10 audio.mp3`) or `separator.update_parameter(segment=smaller_value)` with the API. Alternatively, use CPU processing by adding `-d cpu` to the CLI command or setting `device='cpu'` in the API.
affects: All versions
gotchaDemucs models (especially V4) are primarily trained on 44.1kHz or 48kHz audio. Using input audio with significantly different sample rates (e.g., 96kHz) may result in suboptimal separation quality.fixResample your input audio to 44.1kHz or 48kHz before feeding it to Demucs for best results.
affects: All versions, particularly V4
gotchaBy default, Demucs automatically rescales each output stem to prevent clipping. This can alter the relative volume levels between the separated stems, which might not be desired for certain applications.fixIf you prefer hard clipping without altering relative volumes, use the `--clip-mode clamp` flag in the CLI or set `clip_mode='clamp'` when calling `separator.separate_audio_file()`.
affects: All versions
Upgrade
Version history
4.1.0latest on PyPI · released Jul 11, 2026
Audit
Dependencies
torchrequiredCore deep learning framework for the model.
torchaudiorequiredAudio I/O and transformations, works with PyTorch.
ffmpegoptionalUsed in priority for audio processing and handling various formats. Not a Python dependency, typically needs to be installed system-wide.
soundstretchoptionalUsed for pitch/tempo augmentation during training. Not a Python dependency, typically needs to be installed system-wide (e.g., `brew install sound-touch` on macOS, `apt-get install soundstretch` on Ubuntu).