Stashify: Spotify Music Downloader
Find any track, album or playlist from Spotify on YouTube and save it locally
with cover art, lyrics and full metadata.
English | Bahasa Indonesia
Table of Contents
- About
- Features
- Requirements
- Installation
- Usage
- Configuration
- Data Sources
- Project Structure
- Development
- Testing
- Continuous Integration
- FAQ
- Author
- Disclaimer
- License
About
Stashify is a command line tool that turns a Spotify link into a properly tagged audio file on your machine. It resolves the link against Spotify's public pages, finds the best matching source for each track on YouTube, converts it with FFmpeg and tags it with title, artists, album, track number, release year, cover art and lyrics.
"Your Spotify library, stashed as real files."
Features
Download
| Feature | Description |
|---|---|
| Track, album, playlist, artist | Public Spotify links resolve to a track list and every track downloads (artist links fetch the artist's top 10 tracks, public playlists show up to 50 tracks) |
| No account needed | Metadata comes from Spotify's public embed pages, nothing to create or configure |
| Best-match source | YouTube results are scored on duration and word overlap, the strongest match wins |
| Audio formats | MP3, M4A, Opus, FLAC or WAV, converted through FFmpeg |
| Bitrate control | Choose the bitrate for lossy formats, default 192k |
| Skip existing | Files that already exist are skipped, --overwrite forces a re-download |
| Parallel downloads | N tracks at a time with --jobs (default 2, max 8), faster on large playlists |
| Dry run | --dry-run prints the matched source per track without downloading anything |
Metadata
| Feature | Description |
|---|---|
| Full tagging | Title, artists, album (when known), album artist (when known), track number (albums), disc numbers, release year, cover art |
| Cover art | Original cover embedded, per track for playlists and artists, album cover for albums |
| Lyrics | Plain-text lyrics fetched from a community lyrics API and embedded when found |
| Retag existing files | stashify meta writes the same metadata into files you already have |
| Path templates | {artist} - {title} style templates, subfolders included, safe for any OS |
| Save as JSON | stashify save dumps the resolved metadata without downloading audio |
Sync
| Feature | Description |
|---|---|
| Playlist sync | stashify sync keeps a folder in sync with a playlist: new songs are downloaded, removed songs are deleted |
| Self-contained state | A small stashify.sync.json state file tracks which files Stashify downloaded, it never touches files it did not create |
Requirements
| Dependency | Minimum Version | Notes |
|---|---|---|
| Python | 3.10 | Required |
| FFmpeg | 6 | Required for audio conversion |
Never used a terminal? Start here
How to open a terminal on your OS
Windows
- Press the Windows key, type
PowerShell, then press Enter - A blue window opens. That is where you type commands
macOS
- Press Command + Space, type
Terminal, then press Enter - A window with a prompt opens
Linux
- Open your app launcher and type
terminal, then press Enter - A window with a prompt opens
Every stashify ... command in this guide is typed in that window, followed by Enter.
Installation
Option A: Install from PyPI (easiest)
- Make sure Python 3.10 or newer is installed (
python --versionshould answer) - Make sure FFmpeg is installed (
ffmpeg -versionshould answer). If not:- Windows: download from ffmpeg.org or
winget install ffmpeg - macOS:
brew install ffmpeg - Linux:
sudo apt install ffmpeg(or your distribution's package manager)
- Windows: download from ffmpeg.org or
- Install Stashify from PyPI:
pip install stashify-cli
- Verify the install:
stashify --version
Option B: Install directly from GitHub
pip install git+https://github.com/nekonaru/stashify.git
stashify --version
Needs Python 3.10+ and FFmpeg, same as above.
Option C: Build from source (for development / to read or change the code)
1. Get the project code
I have Git installed
git clone https://github.com/nekonaru/stashify.git
cd stashify
I don't have Git
- Open the repository page on GitHub
- Click the green
Codebutton, chooseDownload ZIP - Extract the ZIP to a folder of your choice
- In the terminal, go into the extracted folder, for example:
cd Downloads/stashify-main
2. Install the dependencies and verify
python -m pip install -e .[dev]
python -m pytest -q
3. Build and check
python -m ruff check src tests
Stashify is a pure Python package. There is no binary to compile; installation is the packaging step.
Usage
First launch
Stashify needs no account, no login and no API keys. Install it, then download:
- Find any Spotify link for a track, album, playlist or artist (public content only)
- Run:
stashify download "https://open.spotify.com/playlist/37i9dQZF1DXcBWIGoYBM5M"
Everyday use
- Download a single track, an album, a playlist or an artist's top tracks by passing their links to
stashify download; files land in your Downloads folder by default - Pick the audio format with
-f mp3|m4a|opus|flac|wav(defaultmp3) - Change the output folder with
-o "D:\Music"and the naming scheme with-t "{album}/{track_number} {title}" - Download up to 8 tracks at once with
--jobs 4(default 2) - Skip cover art or lyrics with
--no-cover/--no-lyrics, or re-fetch everything with--overwrite - Check the whole stack with
stashify doctorwhen a download fails; it reports Python, FFmpeg, network access to Spotify, YouTube and the lyrics API - Preview the match without downloading with
--dry-run - Keep a folder in sync with a playlist:
stashify sync "PLAYLIST_URL" -o "D:\Music\MyList" - Retag files you already have:
stashify meta file1.mp3 file2.mp3 --url "ALBUM_URL" - Export the resolved metadata as JSON:
stashify save "ALBUM_URL" --save-file album.json - Print the source URL that would be used per track:
stashify url "PLAYLIST_URL"
The path template supports {artist}, {artists}, {title}, {album}, {album_artist}, {track_number}, {disc_number} and {release_year}. Use / to create subfolders. Illegal file name characters are removed automatically.
Configuration
Preferences can be stored in a config file; secrets cannot. The default provider needs none.
Config file locations: %APPDATA%\stashify\config.json (Windows), ~/.config/stashify/config.json (macOS and Linux).
| Key | Type | Default | Effect |
|---|---|---|---|
output_dir |
string | your Downloads folder | Output directory for downloads (Windows: %USERPROFILE%\Downloads, macOS and Linux: ~/Downloads or XDG_DOWNLOAD_DIR) |
jobs |
integer | 2 |
Parallel downloads, between 1 and 8 |
audio_format |
string | mp3 |
Default audio format |
bitrate |
string | 192k |
Bitrate for lossy formats |
template |
string | {artist} - {title} |
Output path template |
market |
string | US |
Two-letter market code (only used with --provider api) |
provider |
string | embed |
embed (default, no account) or api (official Web API, needs a Premium-entitled developer app) |
detailed |
boolean | true |
Fetch per-track details (artists, cover, release year) for playlists |
overwrite |
boolean | false |
Re-download files that already exist |
no_cover |
boolean | false |
Never embed cover art |
no_lyrics |
boolean | false |
Never embed lyrics |
Command line flags always win over the config file. The default output directory is your Downloads folder; set the STASHIFY_DOWNLOAD_DIR environment variable, the -o flag or the output_dir key to change it.
Use --provider api with --client-id and --client-secret (or SPOTIFY_CLIENT_ID / SPOTIFY_CLIENT_SECRET environment variables) if you have an official Web API entitlement; it adds ISRC and album metadata for tracks and albums.
Data Sources
Stashify is online only when it resolves metadata, searches for a source or fetches lyrics. Audio is sourced from YouTube.
| Purpose | Source |
|---|---|
| Track, album, playlist and artist metadata | Spotify's public embed pages (default) or the Spotify Web API (--provider api) |
| Cover art | Spotify image CDN (embedded into files) |
| Audio source | YouTube, through yt-dlp |
| Lyrics | lrclib.net (no key required), lyrics.ovh as fallback |
Project Structure
stashify/
├── src/
│ └── stashify/
│ ├── __init__.py # package version
│ ├── __main__.py # python -m stashify entry point
│ ├── cli.py # argument parsing and commands
│ ├── doctor.py # end-to-end stack health check
│ ├── pipeline.py # shared download pipeline
│ ├── spotify.py # Spotify Web API client (optional, --provider api)
│ ├── embed.py # public embed page resolver (default provider)
│ ├── models.py # Track data model
│ ├── sources.py # YouTube search and scoring
│ ├── download.py # yt-dlp download and FFmpeg conversion
│ ├── tagger.py # MP3, M4A, FLAC, Opus and WAV tagging
│ ├── lyrics.py # lrclib.net client (lyrics.ovh fallback)
│ ├── output.py # path templates and file naming
│ ├── sync.py # playlist sync state handling
│ ├── config.py # config file loading
│ └── errors.py # error types
├── tests/ # pytest suite (offline, network mocked)
├── assets/ # logo and icons
├── .github/
│ └── workflows/
│ ├── ci.yml # lint and tests on every push
│ ├── publish.yml # publish to PyPI on demand (OIDC)
│ └── release.yml # draft release from changelog on tags
├── pyproject.toml # packaging and tool configuration
├── SECURITY.md # vulnerability reporting policy
├── LICENSE
├── README.md # main documentation (English)
└── README.id.md # documentation (Bahasa Indonesia)
Development
Publishing to PyPI
One-time setup, done by the maintainer on PyPI:
- Open pypi.org, sign in, go to Account → Publishing
- Add a pending publisher with these exact values:
- Project name:
stashify-cli - Owner:
nekonaru - Repository:
stashify - Workflow name:
publish.yml - Environment name: leave empty
- Project name:
- Push a release tag, then run Publish from the Actions tab on the tag you want to release
The workflow builds the wheel and sdist, checks them with twine check, smoke tests the wheel and publishes via OIDC. No API token is stored anywhere.
Working on the code
- Install the package in editable mode with the dev extras:
python -m pip install -e .[dev] - Make your change
- Run the checks:
python -m ruff check src testsandpython -m pytest -q
Adding a new supported audio format
- Add the format to
AUDIO_FORMATSinsrc/stashify/download.pyand to_CODEC_MAP - Add a tagging path in
src/stashify/tagger.py(see_tag_flacfor an example) - Add a test that renders and retags a short file with FFmpeg, see
tests/test_tagger.py
Testing
Verification before every push, both must be clean:
python -m ruff check src tests
python -m pytest -q
| Check | Requirement |
|---|---|
python -m ruff check src tests |
Must report All checks passed (zero errors, zero warnings) |
python -m pytest -q |
Must pass the full suite |
Lint rules are enforced through the [tool.ruff] section in pyproject.toml.
Continuous Integration
| Workflow | Purpose |
|---|---|
ci.yml |
Ruff and the test suite on Python 3.10 and 3.12, on every push and pull request |
release.yml |
Test suite plus a draft GitHub release built from the changelogs, on tags v* |
FAQ
Something fails; how do I diagnose it?
Run stashify doctor. It checks Python, FFmpeg, the downloads folder, Spotify's embed pages, YouTube search and the lyrics API, and tells you exactly which part works and which does not.
Do I need a Spotify account, login or developer app?
No. The default provider reads Spotify's public pages, exactly what a browser sees without logging in. Nothing to create, nothing to log into, nothing to leak.
Why does my private playlist fail?
Public pages only exist for public content. If the playlist is private, the embed page shows a not-found page and Stashify reports it. Making the playlist public fixes it. Alternatively, official API access to your own playlists requires a Premium-entitled developer app, then stashify ... --provider api with your own credentials.
Why is some metadata missing (ISRC, album name)?
Public pages do not carry every field. Stashify tags what is available: title, artists, duration, release year, cover art, album name and track numbers for albums. ISRC is only available through the official Web API.
Some songs are skipped or fail to download. Why?
Either there is no usable match on YouTube (unreleased tracks, very obscure remixes, private uploads) or yt-dlp needs an update, because YouTube changes frequently. Run pip install --upgrade yt-dlp and try again.
The wrong version of a song gets downloaded. What can I do?
The scorer strongly prefers duration-matched audio with "official" in the title and rejects karaoke, covers and live versions unless you ask for them. Use --dry-run first; if the match keeps coming out wrong, open an issue with the Spotify link.
A file already exists. Will it be overwritten?
No. Existing files are skipped. Pass --overwrite to re-download them.
Can I keep my library folder in sync with a Spotify playlist?
Yes. stashify sync "PLAYLIST_URL" -o "D:\Music\MyList" downloads new tracks and deletes only the files that Stashify downloaded and that have since disappeared from the playlist. Everything else in the folder is untouched.
Author
| Nicolas Dwi Dharma |
| github.com/nekonaru |
Disclaimer
Stashify is an independent open-source project and is not affiliated with or endorsed by Spotify, Google, YouTube, lrclib or the operators of lyrics.ovh. The default provider parses Spotify's public embed pages; this is not a documented API and can change or break at any time. Downloading music may violate the terms of service of those platforms and may infringe copyright in your jurisdiction. Stashify is provided for personal, lawful use only; you are responsible for how you use it.
License
Distributed under the MIT License. See LICENSE for more information.
Metadata
Release files for stashify-cli 1.4.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| stashify_cli-1.4.0.tar.gz | 46.8 kB | With provenance | Details for stashify_cli-1.4.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| stashify_cli-1.4.0-py3-none-any.whl | Python 3 | none | any | Details for stashify_cli-1.4.0-py3-none-any.whl |
Total release size: 83.0 kB
Release files / stashify_cli-1.4.0.tar.gz
| Download URL | stashify_cli-1.4.0.tar.gz |
|---|---|
| Size | 46.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f5696ba6ef681775223c76cd4950922a2c79ada8df86f91da210f47ce3f0aa55
|
|
BLAKE2b-256 checksum How to use checksums |
a1b0ddf792bcaa0fd38a57e0c7a4c2c5e4961073f48d7e5a8375ff18566682a3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.
Transparency logRelease files / stashify_cli-1.4.0-py3-none-any.whl
| Download URL | stashify_cli-1.4.0-py3-none-any.whl |
|---|---|
| Size | 36.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
6fedc49d3b777c8ea3477ee9a7658f405ff25e4ad292d80d3245225a78355671
|
|
BLAKE2b-256 checksum How to use checksums |
736343362705529fa341a9677b181380d296d7504b15d910cd956de3a4ced7bd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.
Transparency logSecurity for stashify-cli 1.4.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for stashify_cli-1.4.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.