Spotify2Local is a zero-friction terminal utility that bridges your Spotify library with your local storage. Built with a responsive TUI, it automatically resolves tracks, fetches the highest quality audio via YouTube, and precisely tags your files with ID3 metadata—all without the setup headache.
- Stupid-simple setup: Works flawlessly out of the box with sensible defaults, while exposing deep configuration options for power users who want control.
- Flawless local libraries: Your music player will thank you. Automatically embeds pristine ID3 tags and high-res cover art for a perfectly organized archive.
- Studio-grade audio: Usig a smart-matching heuristics automatically bypass messy music videos and live performances to secure the highest-quality official tracks.
- Modern TUI No massive list of CLI flags to memorize. Just launch the TUI, search with your keyboard, and watch the progress bars fly.
Install the tool globally using pip (or uv tool):
pip install spotify2localIf you want to contribute or run from the source, Spotify2Local uses uv for fast, reliable dependency management.
Clone the repository and sync the environment:
git clone https://github.com/mserra0/Spotify2Local.git
cd Spotify2Local
uv syncIf installed globally, launch the interactive interface from anywhere by typing:
spotify2localIf developing locally, launch it using:
uv run spotify2localSpotify2Local features a frictionless onboarding experience. If it's your first time running the application, a setup screen inside the terminal will guide you through obtaining your Spotify Developer credentials and automatically securely save them for you.
(For advanced users: Your configuration and cache are stored safely in ~/.spotify2local/)
| Key | Action |
|---|---|
↑ / ↓ |
Navigate playlists |
Enter |
Download selected playlist |
0 |
Enter a Spotify URL manually |
Esc |
Go back or exit |
Important
- Library Requirement: The tool can only process playlists saved to your authenticated account. To download a public playlist, simply open it in Spotify, click the
...menu, and select Add to Your Library before running the tool. - Editorial Restrictions: Spotify restricts direct API access to certain official editorial playlists, which may result in a
403 Forbiddenerror. The fix: Create a new personal playlist, copy all the tracks from the editorial playlist into it, and download your personal playlist instead.
We love community contributions. If you'd like to help improve Spotify2Local, whether it's fixing a bug or adding a new TUI feature, please review our Contributing Guide for instructions on setting up your local environment and submitting a pull request.
This project stands on the shoulders of giants. A special thanks to the maintainers of the following open-source tools: