Skip to main content

Create/update a Spotify playlist from a local m3u playlist

Project description

Convert local playlists to Spotify playlists

Build, Test, Lint PyPI version

Supports m3u and m3u8 files in the Extended format encoded as UTF-8.

Take a look below for more details and debugging tips.


usage: tospotify [-h] [--verbose] [--public] [--convert]
                 [--playlist-id PLAYLIST_ID]
                 spotify_username playlist_path

Create/update a Spotify playlist from a local m3u playlist

positional arguments:
  spotify_username      Spotify username where playlist should be updated.
                        Your email address should work just fine, or could
                        find your user id through e.g. the developer console
  playlist_path         full path to the playlist

optional arguments:
  -h, --help            show this help message and exit
  --verbose             print all the steps when searching for songs
  --public              playlist is public, otherwise private
  --convert             convert from locale default to utf-8
  --playlist-id PLAYLIST_ID
                        do not create a new playlist, instead update the
                        existing playlist with this id


  • Linux/MacOS

      tospotify --verbose "" "D:/playlist/name.m3u"
  • Windows*

      python -m tospotify "" "D:/playlist/name.m3u"

*entry_points does not seem to simply work on Windows


  1. Python >= 3.6

  2. Enable Developer Dashboard and your 'app'.

  3. Setup some environment variables:


export SPOTIPY_CLIENT_ID="<paste-from-dev-dashboard>"
export SPOTIPY_CLIENT_SECRET="<paste-from-dev-dashboard>"
export SPOTIPY_REDIRECT_URI="<your-chosen-uri>"


Same as linux but use set instead of export



Seeing unexpected characters in the log messages is a sign of faulty encoding.

This tool uses m3u8 library to parse the files, which relies on utf-8.

Encoding can be checked by opening the playlist in a text editor, such as Notepad++. If the playlist is in a different encoding, try using the --convert argument which will attempt to convert it to utf-8.

Alternatively, could try importing the playlist into your music player and using its export function to export as utf-8, if it exists. AIMP, for example, can do this.

Songs missing

This might happen when the file is not actually in the extended m3u format. This format looks like

#EXTINF:277,Faun - Sieben Raben
/Music/Selection/Faun - Sieben Raben.mp3

and is populated from file tags. For this example, the mp3 file contains the tags artist = Faun and title = Sieben Raben which then populate the #EXTINF line.

If your playlist only contain paths, try importing it in a (different) music player and exporting again. AIMP, for example, exports in the expected format.

What does tospotify actually do internally?

It tries various cleaning steps and search queries in an attempt to find the correct songs on Spotify.

The extended m3u format is important. As mentioned above, the ground truth is actually the artist and title tags stored in the songs themselves which are then reflected in the playlist. Looking at the example above, the format is essentially artist - title; this implicitly means that dashes - in the artist or title cannot be interpreted properly at the moment. Sorry, AC-DC :(

The tool then uses rules to compute various queries. Take for example the song Every Breath You Take by Sting and the Police. This can be stored in many ways. The artist could be Sting and the Police, Sting;The Police, Sting & the Police, The Police, etc. Then the title could be Every Breath You Take but also Every Breath You Take feat. Sting and other variations. Many of these are not found exactly as such on Spotify.

There can also be live versions, e.g. with title Every Breath You Take [live], covers by other artists, separate recordings of the song, and the list goes on. This song was actually recorded both by The Police with Sting and solo by Sting; both versions are available on Spotify!

Bit more complex than it initially seems :)

So this is what tospotify does; it will try to find the correct song through various rules derived from the data in the playlist.


Take a look at the CONTRIBUTING file for more details. Pull requests are welcome!

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

tospotify-0.3.1.tar.gz (24.2 kB view hashes)

Uploaded source

Built Distribution

tospotify-0.3.1-py3-none-any.whl (25.2 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page