Skip to content
Get packs

Guide · Open source

How to use Spleeter: install, separate stems and tips

Updated · written with AI from the project's own documentation and checked against our catalogue data

Spleeter is an open-source Python library from Deezer that separates a song into stems such as vocals and accompaniment, using pretrained TensorFlow models. This guide walks through installing it, running your first separation from the command line, and handling common problems. It is written for readers comfortable with a terminal and installing Python packages.

Spleeterdeezer/spleeter · ★ 28.5k · MIT

Quick start

  1. 1Install ffmpeg and libsndfile. Install ffmpeg and libsndfile, using Conda on most platforms as the README suggests. Check the PyPI page for the supported Python version first.
  2. 2Install Spleeter. Run pip install spleeter to install the library and its TensorFlow dependency.
  3. 3Get an example file. Download the example audio file from the repository, or use one of your own songs.
  4. 4Run the separate command. Run spleeter separate with the 2stems model and an output folder to split the song into vocals and accompaniment.
  5. 5Check the output. Look for vocals.wav and accompaniment.wav in the output/audio_example folder.
  6. 6Troubleshoot if needed. On Windows, use python -m spleeter if the shortcut fails. On Apple M1, follow the README's linked workaround.

What Spleeter does and who it suits

Spleeter can separate a song into two stems (vocals and accompaniment), four stems (vocals, drums, bass and other), or five stems (vocals, drums, bass, piano and other). You can run it from the command line or call it from your own Python code. People use it to make karaoke tracks, isolate parts of a recording, or build audio tools on top of it.

It is a good fit if you want quick separation and you are comfortable installing Python packages. It is less suitable if you want a point-and-click app with no setup, because the README centres on pip, Docker and the command line.

  • Good fit: musicians or producers who want quick vocal or accompaniment separation
  • Good fit: developers adding stem separation to a Python audio pipeline
  • Good fit: researchers who want a baseline model or want to train their own separation models from isolated sources
  • Not a fit: users who want a graphical app with no setup
  • Not a fit: anyone who needs commercial-grade results with support; the README points to a separate paid product, Spleeter Pro, for that

What you need before installing Spleeter

Spleeter needs Python, ffmpeg, libsndfile and TensorFlow. TensorFlow is installed as a dependency. The README excerpt does not state an exact Python or TensorFlow version, so check the PyPI package page for supported versions before you start.

The README says ffmpeg and libsndfile are best installed with Conda on most platforms. It also notes that it no longer recommends using conda to install Spleeter itself.

  • Python (the exact version is listed on the PyPI package page)
  • ffmpeg
  • libsndfile
  • TensorFlow (installed automatically with Spleeter)
conda install -c conda-forge ffmpeg libsndfile

Install Spleeter with pip

Once ffmpeg and libsndfile are available, install the Spleeter package with pip. The command below is the one given in the README.

If you want to work on the code itself or run its tests, the README describes cloning the repository and using Poetry instead. That path is covered in the development section below.

pip install spleeter

Separate your first song from the command line

The quick start uses an example audio file from the repository. Download it, then run the separate command with the 2stems model. The README uses wget for the download; if you do not have wget, use another download tool.

The command writes output to the folder you name with -o. For this example, you should get two files, vocals.wav and accompaniment.wav, in the output/audio_example folder.

To separate into four or five stems, the README describes separate models named spleeter:4stems and spleeter:5stems. The two-stem model is the one shown in the quick start.

  • Use -p to choose the model, for example spleeter:2stems
  • Use -o to choose the output folder
  • Your output files appear in a subfolder named after the input file
wget https://github.com/deezer/spleeter/raw/master/audio_example.mp3 spleeter separate -p spleeter:2stems -o output audio_example.mp3

Use Spleeter from Python code

Spleeter can also be used directly in your own Python pipeline as a library. The README links to an API reference for the Separator class in the project wiki, which is where you should look for the exact calls and parameters. This guide does not reproduce that API, so check the wiki before writing code against it.

If you prefer not to install anything, the README points to a Google Colab notebook that runs the project without local setup.

  • Library reference: the Separator class in the project wiki
  • Try it first without installing: the Google Colab notebook linked in the README
  • Docker is also supported; the README links to a Docker image guide

Fix common problems: Apple M1 and Windows

The README notes known issues on Apple M1 chips, mostly due to TensorFlow compatibility. Until these are fixed, it links a workaround in a GitHub issue thread. Read that thread before installing on an M1 Mac.

On Windows, the README says the shortcut command spleeter sometimes does not work properly. The suggested workaround is to run the module directly with python -m spleeter in place of spleeter. For other errors, the README suggests checking the project's FAQ page and its list of open issues.

  • Apple M1: follow the workaround linked from the README's quick start
  • Windows: replace spleeter separate with python -m spleeter separate
  • Other errors: check the FAQ wiki page and the open issues list on GitHub
python -m spleeter separate -p spleeter:2stems -o output audio_example.mp3

Set up a development copy and run the tests

If you want to contribute or run the test suite, the README says the project is managed with Poetry. Clone the repository, install Poetry, install the dependencies, then run pytest against the tests folder.

The README asks contributors to read the guidelines in the repository before opening a pull request.

git clone https://github.com/Deezer/spleeter && cd spleeter pip install poetry poetry install poetry run pytest tests/

What people use it for

  • Making a karaoke version of a song by keeping the accompaniment file
  • Isolating vocals from a recording for transcription or remixing
  • Splitting a track into drums, bass and other stems with the 4stems model
  • Adding stem separation as a step in a Python audio pipeline
  • Using the pretrained models as a baseline for music source separation research

Frequently asked questions

Is Spleeter free to use?

Spleeter's code is MIT-licensed, according to the README. The README also says that if you use it on copyrighted material, you should get proper authorisation from the rights owners first.

What do I need to install Spleeter?

You need Python, ffmpeg, libsndfile and TensorFlow. TensorFlow is installed as a dependency, and the README suggests installing ffmpeg and libsndfile with Conda on most platforms.

How do I install Spleeter?

Install ffmpeg and libsndfile first, then run pip install spleeter. The README describes this as the quick start route.

Why does the spleeter command not work on Windows?

The README says the shortcut command sometimes fails on Windows. Run python -m spleeter separate instead, which the README reports works.

Does Spleeter work on Apple M1 Macs?

The README notes known issues on Apple M1 chips, mostly due to TensorFlow compatibility. It links a workaround in a GitHub issue, which you should follow until these issues are fixed.

Are there alternatives to Spleeter?

The projects listed as comparable are Demucs, Open-Unmix, Asteroid and Ultimate Vocal Remover. This guide does not compare their quality or speed, so test them on your own material before choosing.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Spleeter suits people who are comfortable with Python and a terminal and want quick vocal or accompaniment separation, or a pretrained baseline for research. If you want a click-to-run app with no setup or commercial support, look at a GUI product or the paid Spleeter Pro option rather than the open-source library.

Install options & downloads