Skip to main content
Stashify logo

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.

Release CI Python Platform License Status


English | Bahasa Indonesia


Table of Contents


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

  1. Press the Windows key, type PowerShell, then press Enter
  2. A blue window opens. That is where you type commands

macOS

  1. Press Command + Space, type Terminal, then press Enter
  2. A window with a prompt opens

Linux

  1. Open your app launcher and type terminal, then press Enter
  2. 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)

  1. Make sure Python 3.10 or newer is installed (python --version should answer)
  2. Make sure FFmpeg is installed (ffmpeg -version should 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)
  3. Install Stashify from PyPI:
pip install stashify-cli
  1. 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
  1. Open the repository page on GitHub
  2. Click the green Code button, choose Download ZIP
  3. Extract the ZIP to a folder of your choice
  4. 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:

  1. Find any Spotify link for a track, album, playlist or artist (public content only)
  2. 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 (default mp3)
  • 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
  • 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 lyrics.ovh (no key required)

Project Structure

stashify/
├── src/
│   └── stashify/
│       ├── __init__.py           # package version
│       ├── __main__.py           # python -m stashify entry point
│       ├── cli.py                # argument parsing and commands
│       ├── 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             # lyrics.ovh client
│       ├── 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:

  1. Open pypi.org, sign in, go to Account → Publishing
  2. Add a pending publisher with these exact values:
    • Project name: stashify-cli
    • Owner: nekonaru
    • Repository: stashify
    • Workflow name: publish.yml
    • Environment name: leave empty
  3. 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

  1. Install the package in editable mode with the dev extras: python -m pip install -e .[dev]
  2. Make your change
  3. Run the checks: python -m ruff check src tests and python -m pytest -q

Adding a new supported audio format

  1. Add the format to AUDIO_FORMATS in src/stashify/download.py and to _CODEC_MAP
  2. Add a tagging path in src/stashify/tagger.py (see _tag_flac for an example)
  3. 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

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
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 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.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for stashify-cli 1.3.0
File Size Uploaded Provenance Actions
stashify_cli-1.3.0.tar.gz 43.4 kB With provenance Details for stashify_cli-1.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for stashify-cli 1.3.0
File Interpreter ABI Platform Actions
stashify_cli-1.3.0-py3-none-any.whl Python 3 none any Details for stashify_cli-1.3.0-py3-none-any.whl

Total release size: 77.0 kB

Release files / stashify_cli-1.3.0.tar.gz

Download URL stashify_cli-1.3.0.tar.gz
Size 43.4 kB
Tags Source
SHA-256 checksum
How to use checksums
fd2170ec61fd357a0cbf558b25884862950bcccd5efa4f20dba3041323d9536f
BLAKE2b-256 checksum
How to use checksums
9b81cc0e1f7929407314a95b8f262b5612a607e3d0568caab9f3ccc4238adae0
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 log

Release files / stashify_cli-1.3.0-py3-none-any.whl

Download URL stashify_cli-1.3.0-py3-none-any.whl
Size 33.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
5e23480cfd1f89fe10b244c49b5079c63e9db235d975423c160797462a3742c5
BLAKE2b-256 checksum
How to use checksums
25861cf07fa786e95517e004acfebc3397046cda5b5e1afd18d982db4b091087
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 log

Security for stashify-cli 1.3.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.

Select from 2 files

Attestation for stashify_cli-1.3.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 log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page