Spleeter: Deezer's Source Separation Library, Installed and Used

What Spleeter separates, and who the library is actually for

Spleeter takes a mixed audio file and writes out the individual sources it estimates are inside it. The README lists three pretrained configurations: 2 stems (vocals and accompaniment), 4 stems (vocals, drums, bass, other) and 5 stems (vocals, drums, bass, piano, other). It is a Python library built on TensorFlow, published by Deezer, and licensed under MIT.

The intended user is not someone who wants a button in a DAW. It is a developer or researcher who wants separation as a step in a pipeline: batch processing a catalogue, preparing training data, or embedding a separator inside another application. The README states the design goal directly, that Spleeter can be used from the command line as well as directly in a development pipeline as a Python library. Training your own model is also in scope, provided you already have a dataset of isolated sources.

The repository also notes that many forks expose Spleeter through a GUI or a website, and that Deezer does not host, maintain or support those. If you arrived looking for a Spleeter app or a Spleeter GUI, that is the relevant sentence: the upstream project ships a CLI, a Python API and a Docker image, not an interface.

The separator pipeline: config, TensorFlow graph, waveform output

The mechanism visible in the repository is a configuration-driven inference pipeline. Separation parameters live in the configs/ directory, and the CLI selects one with the -p flag, as in spleeter:2stems, which maps to a named preset. Each preset fixes the number of output stems and points at a pretrained model.

At run time the audio is decoded, passed through the pretrained TensorFlow model, and the estimated sources are written as separate waveform files into an output directory derived from the input filename. The README's own example produces vocals.wav and accompaniment.wav inside output/audio_example. Because the models are pretrained and shipped with the package, there is no training step in the default path.

The repository layout reflects this split cleanly: configs/ holds the presets, spleeter/ holds the library code, tests/ holds the test suite, and docker/ plus conda/ hold packaging for those two distribution routes. The README also points to a wiki page on separation performances and states that the 2 stems and 4 stems models perform well on the musdb dataset. That claim is Deezer's, measured on musdb, not a general guarantee about arbitrary recordings.

Installing Spleeter and separating your first file

The README requires ffmpeg and libsndfile before anything else. Its quick start shows installing those with conda, then installing Spleeter with pip. Note the warning immediately below that block: the project no longer recommends using conda to install spleeter itself, so treat conda as the route for the two native dependencies, not for the package.

# install dependencies using conda
conda install -c conda-forge ffmpeg libsndfile
# install spleeter with pip
pip install spleeter

Next, fetch the example audio the repository ships at the top level. The README uses wget and notes you can substitute another download tool.

wget https://github.com/deezer/spleeter/raw/master/audio_example.mp3

Then run the separator against that file with the 2 stems preset and an output directory.

spleeter separate -p spleeter:2stems -o output audio_example.mp3

The README states you should get vocals.wav and accompaniment.wav in the output/audio_example folder. If those two files appear, the install is sound and you can point the same command at your own material by swapping the filename. The first run downloads the pretrained model weights, so expect the initial invocation to take longer than subsequent ones.

If you prefer not to install anything locally, the README links a Google Colab notebook that runs the same workflow in a browser. For container users, the README points to a Docker image under the deezer/spleeter name on Docker Hub, and the docker/ directory in the repository holds the build files.

TensorFlow version pinning, Apple silicon, and the ffmpeg prerequisite

The sharpest limitation is environmental. Spleeter depends on TensorFlow, and the README carries an explicit warning that there are known issues with Apple M1 chips, mostly due to TensorFlow compatibility, and links a workaround in issue 607. On an M1 or later Mac, plan for that workaround rather than a clean pip install.

The second constraint is that ffmpeg and libsndfile are external native dependencies, not Python packages. If ffmpeg is missing or built without the codecs your input needs, decoding fails before any model runs. That is a system packaging problem, and it is the most common reason a first run dies on a machine where pip reported success.

The third is the CLI surface itself. The README flags that the 2.1.0 release introduced breaking changes, including new CLI option naming for input and the removal of a dedicated GPU package. Anyone copying older tutorials will find flags that no longer match. The CHANGELOG is the authoritative place to check what moved.

Finally, the separation is a fixed taxonomy. There is no preset that isolates guitar, strings, or a specific instrument outside the listed stem sets. If your target source is not vocals, drums, bass, piano or the residual other, the pretrained models do not address it, and the only route is training your own model on a dataset of isolated sources.

Spleeter versus Demucs: different bets on model architecture

The comparison people search for is spleeter versus demucs, and the difference is architectural rather than cosmetic. Spleeter is built on TensorFlow, ships fixed pretrained presets selected by config name, and exposes separation through a CLI and a Python API. Demucs, from Meta's research group, is built on PyTorch and is a waveform-domain model; its pretrained models are also distributed through its own package and CLI.

The practical consequences follow from that. Spleeter's TensorFlow dependency is what produces the Apple silicon friction documented in its issue tracker; a PyTorch-based separator has a different set of platform problems. Spleeter's presets are fixed at 2, 4 and 5 stems with named instruments; a waveform model may expose a different stem set and different quality characteristics on the same input. Neither repository publishes a head-to-head benchmark in the sources consulted here, so the honest position is that you should run both on a sample of your own audio before choosing.

What Spleeter does have, according to the README, is adoption inside commercial tools. The README lists iZotope RX 8's Music Rebalance, Steinberg Spectralayers 7's Unmix, Acon Digital Acoustica 7, VirtualDJ's stem isolation and Algoriddim's NeuralMix and djayPRO as products that have used Spleeter pretrained models. That is evidence the models were good enough to ship in shipping software, and it is also historical: it says nothing about how they compare to models released since.

Licence, maintenance signals, and what upgrading costs you

Spleeter is MIT licensed, as stated in the repository's LICENSE file and in the pyproject.toml metadata. MIT is permissive: it allows commercial use, modification and redistribution, subject to the usual requirement to preserve the copyright notice and licence text. It does not grant trademark rights, and it does not cover the pretrained model weights as a separate legal question, which the repository does not address. If your use is commercial and the model provenance matters to your legal team, that is a question for them, not something this article can settle.

The maintenance picture is mixed and worth stating plainly. The last push to the repository was on 2026-06-18, so the codebase has seen recent activity. The most recent tagged release listed is v2.3.0 from 2021-09-03, while pyproject.toml declares version 2.4.2, which means the version in the tree is ahead of the newest release tag. If you pin to a release, you are pinning to something older than master.

Upgrade cost is dominated by two things. First, the 2.1.0 breaking changes to CLI option naming mean any scripts written against pre-2.1 syntax need editing. Second, TensorFlow version drift: the pyproject classifiers list Python 3.8 through 3.11, so a Python 3.12 or later environment is outside the declared support range and you should expect to manage that yourself. Read the CHANGELOG before moving versions, and re-run your separation on a known file afterward to confirm output filenames and stem counts did not change.

Editorial conclusion

Adopt Spleeter if you need a scriptable, MIT-licensed separator you can call from Python or a shell, and if 2, 4 or 5 fixed stems cover your material. Do not adopt it if you need a GUI, a plugin, or separation quality that beats newer architectures, and do not expect the open source repository to ship the faster processing Deezer advertises for Spleeter Pro. Before committing, verify three things on your own machine: that TensorFlow installs cleanly for your Python version, that ffmpeg and libsndfile are present, and that the 2stems output on one of your own files is good enough for the downstream task.

Frequently asked questions

Official sources

1. deezer/spleeter on GitHub
2. License: MIT
3. Project website
4. README
5. Releases