Match your local files to Spotify's database, so you can listen to them anywhere you go!

BoscoDomingo, updated 🕥 2022-05-02 16:18:45


Logo image

Cross-platform tool to match your local files to Spotify's database. Easily transfer all your local songs over to a playlist on Spotify in just a few minutes. Migrating your local library has never been easier!

Before you start (5 minutes)

This isn't infalible, and it would be quite surprising if it matched 100% of songs. Be aware you'll probably have to do a bit of manual searching, but this will significantly reduce that amount by automating the majority of the process.

On to the requirements and instructions:

Install Python >3.6

Make sure you have Python 3.6 or later installed, preferably the latest version. We tested it with Python 3.8.4 on a x64 PC with Windows 10 You'll need to install the libraries spotipy and eyed3

I suggest you create a virtual environment so you don't mess other libraries, with the built in venv


For this, simply open a Terminal in the folder that the code is in (type 'wt' in the Windows Explorer address bar for Windows Terminal, or 'cmd' if that doesn't work) and write the following commands (make sure to change for your desired folder name):

python python -m pip install --upgrade pip python -m venv <MyEnv> <MyEnv>\Scripts\activate.bat # <- on cmd <MyEnv>\Scripts\Activate.ps1 # <- on PowerShell

This should make the terminal look something like this:

Terminal with venv active

To exit the virtual environment, simply type deactivate and press Enter. It is not necessary, though, as we'll be working within the environment and you can just close the console once it is done.

Installing the libraries

You can now install spotipy, tinytag and eyed3 with:

python pip install -r .\requirements.txt or python pip install --upgrade spotipy pip install -U eyed3 pip install -U tinytag

Creating a Spotify Developer Application

Head over to the Spotify Developer website, log in with your Spotify account and create a new application (name doesn't matter).

Copy the client id and the client secret, open the settings and make sure to add a URL to the "Redirect URIs". It doesn't really matter what, try https://localhost/ if not sure, but take note of it because you'll need to write it in the source code later.

With these 3, open the file with whatever IDE or Text Editor you like (preferably Notepad++, Wordpad or TextEdit if you use a text editor), and change this bit of code:

connect_to_spotify code

(Use the Find function to find it if you don't see it. It is inside the connect_to_spotify function)

Paste the aforementioned ids and the URL you chose in the corresponding lines. With this, setup is done and you can now use the tool!

Using SpotifyMatcher

Usage is very, very simple. You only have to call the program from a Terminal of your choice with python ./ username playlist_id (may have to use python3 if you have several versions of Python installed or if you're not on Windows).

With this, the application should open a new tab on your default browser. Accept the permissions it asks for, and copy the URL of the page it takes you to (if it's localhost, it will probably not load anything, that's perfectly ok. We only need the URL). Paste it in the terminal.

With that, authentication should be done and you can move on to the good stuff. Simply paste the path to your music directory (Tip: right click the address bar on Windows Explorer, 'Copy address as text'). You can also bypass this step if you manually enter a path in the source code. Simply find the music_dir variable and paste it there before you execute the program:


If the path is valid, the program should start identifying your files and subsequently searching Spotify for a match. This may take several minutes, depending on your processor, internet speed, number of files... Just be patient!

Once done, if you specified a playlist_id it will try to add the matches to said playlist.


If you don't own said playlist, can't add tracks or it has been deleted, the program will fail, and you'll have to start again, so make sure you have said permissions.

We recommend either leaving it blank, so the program creates a new one for you or creating a new playlist and getting its id (simply open it in the browser and copy the final string of numbers and letters).

Only thing left is to check the .txt file with the failed matches and search those manually (I know, I know... blame Spotify's inconsistent artist - title debacle!)

Getting your username and playlist ids


Open Spotify on PC, go to your user profile and click the 3 dots. Click share and "Copy Spotify URI". Paste and remove the spotify:user:

You can also copy your profile link and just take the stuff after /user but before the ?

Playlist id

We recommend you don't actually use a playlist id and rather leave it blank so the program creates one for you automatically, but if you insist, simply open the playlist, click the 3 dots > Share > Copy Spotify URI. As with the username, remove the spotify:playlist:.

Alternatively, you can simply copy the playlist link and just take the final string of numbers and letters. Same thing.


HTTPS Error for POST to playlist due to Insufficient client scope

opened on 2021-10-17 11:48:31 by enthalith

HTTP Error for POST to with Params: {'position': None} returned 403 due to Insufficient client scope

Getting this error where it is unable to post it to the playlist I selected, even when I did not choose a playlist, it would display this error instead "WARNING: There was an error creating the playlist. Please, create one manually and paste its id in the terminal, after your username"

Edit: Additionally, is there a way to make it read japanese and korean characters? Most of my songs are japanese and korean and it breaks the script each time it encounters one.

Improve stability

opened on 2021-03-26 17:27:31 by jakelauer

This PR fixes a couple of issues I ran into while using this tool.

  • Enables partial uploads so that you can determine if there is a problem early, rather than waiting for the entire scan to finish
  • Fixes a place that was failing to pass the playlist_id
  • Other minor fixes


SpotifyMatcher v1.2 2022-05-02 16:12:54

Now supporting UTF-8 encoding (thanks @Lolzep )

What's Changed

  • Update by @Lolzep in

New Contributors

  • @Lolzep made their first contribution in

Full Changelog:

SpotifyMatcher v1.1.2 2021-10-17 18:39:06

Minor changes, mostly dealing with cleaning up code. Functionally the same as v1.1.1

Full Changelog:

SpotifyMatcher v1.1.1 2020-12-30 23:34:11

Using OAuth for user authentication and refreshing token upon expiration, so the program won't stop working at the 1 hour mark.

SpotifyMatcher v1.0 2020-08-17 01:06:20

First version of the tool. Enjoy!

Bosco Domingo

Backend Engineer @ Colkie. B.Eng Software Engineering from UPM. Dabbling in everything from ML, to SWE, Game Dev and Program Management

GitHub Repository