A fast, all-in-one scriptable music downloader for Qobuz, Deezer, Tidal, SoundCloud and Spotify.
Important
Bookmark these mirrors. GitHub has taken down repositories before, so streamrip lives in three places:
- opencommit.eu/Stensel8/streamrip -- the primary one: development and the dependency updates happen here
- github.com/Stensel8/streamrip -- kept in sync with opencommit.eu
- repos.codetrunk.eu/Stensel8/streamrip -- copies GitHub automatically every 8 hours
Note
A fork of nathom/streamrip that I keep working and up to date (changes). It needs the latest stable Python, and streaming services change their APIs without notice, so things can break. Development happens on opencommit.eu, the primary platform. I also look at the issues and pull requests on GitHub, and the issues on codetrunk.eu, now and then.
Caution
pip install streamrip, the AUR package and brew install streamrip install
upstream streamrip, which doesn't work on Python 3.15.
- Tracks, albums, playlists, discographies and labels, your liked tracks and albums on Tidal and Deezer, Spotify links (details), CSV lists (details) and last.fm playlists
- Interactive search on every source
- Tags, cover art and lyrics, and if you like conversion to FLAC, ALAC, AIFF, MP3, AAC, OGG or Opus
- Remembers what it downloaded;
streamrip repairretries what failed
Download Source code (ZIP) from the latest release on GitHub
and extract it, or git clone https://opencommit.eu/Stensel8/streamrip. Then run
the installer in that folder:
./install.sh # Linux, macOS
powershell -ExecutionPolicy Bypass -File .\install.ps1 # WindowsIt installs streamrip and ffmpeg into a .venv there with
uv, and Python 3.15 if you don't have it. Run
.venv/bin/streamrip (Windows: .venv\Scripts\streamrip.exe), or activate the
venv and type streamrip.
Already have uv? Download the .whl from the
latest release and:
uv tool install ./streamrip-*.whluv fetches Python 3.15 itself if you don't have it. Add the browser and
ffmpeg extras for the automatic-login browser and a bundled ffmpeg:
uv tool install "./streamrip-*.whl[browser,ffmpeg]".
Everything built in, ffmpeg too, for amd64 and arm64:
mkdir -p streamrip
podman run --rm -it -v ./streamrip:/data -v ~/Music:/data/Music \
opencommit.eu/stensel8/streamrip url <link>Downloads go to your own music folder, ~/Music;
config and databases stay in ./streamrip. The same image is on
ghcr.io/stensel8/streamrip. Docker, SELinux and more:
docs/container.md.
nix run . -- url <link> # x86_64 Linux, from this checkoutMore in docs/nix.md.
streamrip url https://tidal.com/browse/album/234793 # an album, artist, playlist or track
streamrip url <link> <link> # several at once
streamrip file urls.txt # the links in a file, one per line
streamrip id tidal album 234793 # by source, type and ID
streamrip search tidal album 'linkin park meteora' # search, and pick
streamrip search --first tidal track 'linkin park in the end' # search, and take the first
streamrip csv linkin-park.csv # a CSV list of tracks
streamrip lastfm https://www.last.fm/user/nathan3895/playlists/12126195
streamrip --codec mp3 url <link> # convert while downloading
streamrip --quality 2 url <link> # at most CD quality
streamrip repair # retry what failed
streamrip config open # every option, explainedLinks from Qobuz, Deezer, SoundCloud and Spotify work the same way, and so do
your likes: https://listen.tidal.com/my-collection/tracks (or /albums), and a
Deezer profile's /loved or /albums. Every command has --help. Each source is asked for its highest quality, stepping down
when a track doesn't have it; --quality sets the highest to ask for:
| Quality | Audio | Sources |
|---|---|---|
| 0 | 128 kbps MP3 (Deezer), 256 kbps AAC (Tidal) | Deezer, Tidal |
| 1 | 320 kbps MP3 or AAC | Deezer, Tidal, Qobuz |
| 2 | 16 bit, 44.1 kHz (CD) | Deezer, Tidal, Qobuz |
| 3 | 24 bit, ≤ 96 kHz (Qobuz), ≤ 192 kHz (Tidal) | Tidal, Qobuz |
| 4 | 24 bit, ≤ 192 kHz | Qobuz |
The search menu shows each result's cover. A terminal that can show images
shows the real one: Ghostty, Kitty, WezTerm, Konsole or foot on Linux, Windows
Terminal, iTerm2 on macOS, and VS Code with terminal.integrated.enableImages.
Others get it in colored blocks. This works from the container and over SSH too.
streamrip asks for what it needs the first time you use a source, and saves it in the config. A login that stops working is asked for again.
| Source | You need |
|---|---|
| Qobuz | A subscription, or the albums you bought. Log in with an isolated browser window, your own browser, or by hand. |
| Tidal | A subscription. Log in with a link on any device (twice, for hi-res). |
| Deezer | The arl cookie of a logged-in session: an isolated browser window, or by hand. |
| SoundCloud | Nothing. |
| Spotify | An app of your own, and Premium on the account that owns it. The audio comes from YouTube Music and is not lossless. |
Details per source: Logging in, Spotify.
- Spotify: the app you need, what works, and why it isn't lossless
- CSV lists: download a list exported from Music-Sync, Exportify or a spreadsheet
- Lyrics: where they come from, and how to turn the lookup off
- Podman and Docker: the image, its volume, and building it yourself
- Nix: the flake and its development shell
Report problems in the issue tracker on opencommit.eu
(or on GitHub).
For code, uv sync --all-extras sets things up, and uv run pytest and
uv run ruff check . && uv run ruff format . should pass before you open a pull
request to dev. Tests that drive a real browser are skipped when there is none.
CI leaves the tests about logins and sessions out; checks/
runs those, the checks with real accounts and everything else CI does, by hand.
streamrip was written by nathom (consider sponsoring nathom); this fork builds on everyone who sent fixes upstream, credited in CHANGELOG.md. Thanks to Vitiko98, Sorrow446 and DashLt for their contributions. streamrip was inspired by rip, qobuz-dl, Qo-DL Reborn, Tidal-Media-Downloader and scdl. The lyrics lookup uses LRCLIB. The Spotify support borrows from three projects, credited in docs/spotify.md.
I will not be responsible for how you use streamrip. By using streamrip, you agree to the terms and conditions of the Qobuz, Tidal, Deezer and Spotify APIs, and of YouTube, which the audio of Spotify tracks comes from.