📚 Documents: musicdl.readthedocs.io

🎧 Live Demo · MusicSquare (音乐广场)

🛠 Source Code (MusicSquare)

MusicSquare is a browser-based music playground — search, play, and download tracks directly in your browser.
⚠️ For learning and testing only: please respect copyright and the terms of each music platform.

🎉 What's New

• 2025-12-02: Released musicdl v2.6.2 — support parsing AppleMusicClient encrypted audio streams, along with some minor optimizations.
• 2025-12-01: Released musicdl v2.6.1 — we have provided more comprehensive documentation and added four new music search and download sources, i.e., MituMusicClient, GequbaoMusicClient, YinyuedaoMusicClient, and BuguyyMusicClient, which allow you to download a large collection of lossless tracks.
• 2025-11-30: Released musicdl v2.6.0 — by tuning and improving the search arguments, we have significantly increased the search efficiency for some music sources, added support for searching and downloading music from Apple Music and MP3 Juice, and made several other minor optimizations.
• 2025-11-25: Released musicdl v2.5.0 — supports searching and downloading from YouTube Music and make musicdl more robust.
• 2025-11-21: Released musicdl v2.4.6 — fixed bugs caused by mismatched arguments in MusicClient.download and optimized music sources.
• 2025-11-19: Released musicdl v2.4.5 — fix potential in-place modified bugs in HTTP requests.
• 2025-11-19: Released musicdl v2.4.4 — some minor improvements and bug fixes.

🎵 Introduction

A lightweight music downloader written in pure Python. Like it? ⭐ Star the repository to stay up to date. Thanks!

⚠️ Disclaimer

This project is for educational use only and is not intended for commercial purposes. It interacts with publicly available web endpoints and does not host or distribute copyrighted content. To access paid tracks, please purchase or subscribe to the relevant music service—do not use this project to bypass paywalls or DRM. If you are a rights holder and believe this repository infringes your rights, please contact me and I will promptly address it.

🎧 Supported Music Client

MusicClient (EN)	MusicClient (CN)	Search	Download	Code Snippet
FiveSingMusicClient	5SING音乐	✓	✓	fivesing.py
KugouMusicClient	酷狗音乐	✓	✓	kugou.py
KuwoMusicClient	酷我音乐	✓	✓	kuwo.py
LizhiMusicClient	荔枝FM	✓	✓	lizhi.py
MiguMusicClient	咪咕音乐	✓	✓	migu.py
NeteaseMusicClient	网易云音乐	✓	✓	netease.py
QianqianMusicClient	千千音乐	✓	✓	qianqian.py
QQMusicClient	QQ音乐	✓	✓	qq.py
XimalayaMusicClient	喜马拉雅	✓	✓	ximalaya.py
JooxMusicClient	JOOX (QQ音乐海外版)	✓	✓	joox.py
TIDALMusicClient	TIDAL (提供HiFi音质的流媒体平台)	✓	✓	tidal.py
YouTubeMusicClient	油管音乐	✓	✓	youtube.py
AppleMusicClient	苹果音乐	✓	✓	apple.py
MP3JuiceMusicClient	MP3 Juice (SoundCloud+YouTube源)	✓	✓	mp3juice.py
MituMusicClient	米兔音乐	✓	✓	mitu.py
GequbaoMusicClient	歌曲宝	✓	✓	gequbao.py
YinyuedaoMusicClient	音乐岛	✓	✓	yinyuedao.py
BuguyyMusicClient	布谷音乐	✓	✓	buguyy.py

🧪 Playground

Here are some projects built on top of musicdl,

Project (EN)	Project (CN)	WeChat Article	Project Location
Music downloader GUI	音乐下载器GUI界面	click	musicdlgui
Singer lyrics analysis	歌手歌词分析	click	singerlyricsanalysis
Lyric-based song snippet retrieval	歌词获取歌曲片段	click	searchlyrics

For example, the Music Downloader GUI looks/works like this,

📦 Install

You have three installation methods to choose from,

# from pip
pip install musicdl
# from github repo method-1
pip install git+https://github.com/CharlesPikachu/musicdl.git@master
# from github repo method-2
git clone https://github.com/CharlesPikachu/musicdl.git
cd musicdl
python setup.py install

Some of the music downloaders supported by musicdl require additional CLI tools to function properly, mainly for decrypting encrypted search/download requests and audio files. These CLI tools include FFmpeg and Node.js. Specifically,

• FFmpeg: At the moment, only TIDALMusicClient and AppleMusicClient depends on FFmpeg for audio file decoding. If you don’t need to use TIDALMusicClient and AppleMusicClient when working with musicdl, you don’t need to install FFmpeg. After installing it, you should run the following command in a terminal (Command Prompt / PowerShell on Windows, Terminal on macOS/Linux) to check whether FFmpeg is on your system PATH:

  ffmpeg -version

  If FFmpeg is installed correctly and on your PATH, this command will print the FFmpeg version information (e.g., a few lines starting with ffmpeg version ...). If you see an error like command not found or 'ffmpeg' is not recognized as an internal or external command, then FFmpeg is either not installed or not added to your PATH.

• Node.js: Currently, only YouTubeMusicClient in musicdl depends on Node.js, so if you don’t need YouTubeMusicClient, you don’t have to install Node.js. Similar to FFmpeg, after installing Node.js, you should run the following command to check whether Node.js is on your system PATH:

  node -v (npm -v)

  If Node.js is installed correctly, node -v will print the Node.js version (e.g., v22.11.0), and npm -v will print the npm version. If you see a similar command not found / not recognized error, Node.js is not installed correctly or not available on your PATH.

• GPAC: GPAC is an open-source multimedia framework for packaging, processing, and streaming formats like MP4, DASH, and HLS. In musicdl, this library is mainly used for handling AppleMusicClient audio streams, so if you don’t need AppleMusicClient support, you don’t need to install it. After installing GPAC, you need to make sure all of its executables are available in your system PATH. A quick way to verify this is that you should be able to run

  python -c "import shutil; print(shutil.which('MP4Box'))"

  in Command Prompt and get the full path without an error.

• Bento4: Bento4 is an open-source C++ toolkit for reading, writing, inspecting, and packaging MP4 files and related multimedia formats. In musicdl, this library is mainly used for handling AppleMusicClient audio streams, so if you don’t need AppleMusicClient support, you don’t need to install it. After installing Bento4, you need to make sure all of its executables are available in your system PATH. A quick way to verify this is that you should be able to run

  python -c "import shutil; print(shutil.which('mp4decrypt'))"

  in Command Prompt and get the full path without an error.

• N_m3u8DL-RE: N_m3u8DL-RE is a powerful open-source command-line tool for downloading, decrypting, and muxing HLS/DASH (m3u8/mpd) streaming media into local video files. In musicdl, this library is mainly used for handling AppleMusicClient audio streams, so if you don’t need AppleMusicClient support, you don’t need to install it. After installing N_m3u8DL-RE, you need to make sure all of its executables are available in your system PATH. A quick way to verify this is that you should be able to run

  python -c "import shutil; print(shutil.which('N_m3u8DL-RE'))"

  in Command Prompt and get the full path without an error.

🚀 Quick Start

Typical Examples

Here, we provide some common musicdl use cases to help you quickly get started with the tool.

If you want the quickest way to run musicdl to verify that your environment meets its basic requirements and that musicdl has been installed successfully, you can write and run the following code,

from musicdl import musicdl

music_client = musicdl.MusicClient(music_sources=['MiguMusicClient', 'NeteaseMusicClient', 'QQMusicClient'])
music_client.startcmdui()

The above code runs musicdl using MiguMusicClient, NeteaseMusicClient, and QQMusicClient as both the search sources and download sources.

Of course, you can also run musicdl by entering the following equivalent command directly in the command line,

musicdl -m NeteaseMusicClient,MiguMusicClient,QQMusicClient

The demonstration is as follows,

You can also use musicdl --help to see the detailed usage of the musicdl command-line tool, as follows:

Usage: musicdl [OPTIONS]

Options:
  --version                       Show the version and exit.
  -k, --keyword TEXT              The keywords for the music search. If left
                                  empty, an interactive terminal will open
                                  automatically.
  -m, --music-sources, --music_sources TEXT
                                  The music search and download sources.
                                  [default: MiguMusicClient,NeteaseMusicClient
                                  ,QQMusicClient]
  -i, --init-music-clients-cfg, --init_music_clients_cfg TEXT
                                  Config such as `work_dir` for each music
                                  client as a JSON string.
  -r, --requests-overrides, --requests_overrides TEXT
                                  Requests.get kwargs such as `headers` and
                                  `proxies` for each music client as a JSON
                                  string.
  -c, --clients-threadings, --clients_threadings TEXT
                                  Number of threads used for each music client
                                  as a JSON string.
  -s, --search-rules, --search_rules TEXT
                                  Search rules for each music client as a JSON
                                  string.
  --help                          Show this message and exit.

If you want to change the download path for the music files, you can write the following code:

from musicdl import musicdl

init_music_clients_cfg = dict()
init_music_clients_cfg['MiguMusicClient'] = {'work_dir': 'migu'}
init_music_clients_cfg['NeteaseMusicClient'] = {'work_dir': 'netease'}
init_music_clients_cfg['QQMusicClient'] = {'work_dir': 'qq'}
music_client = musicdl.MusicClient(music_sources=['MiguMusicClient', 'NeteaseMusicClient', 'QQMusicClient'])
music_client.startcmdui()

Alternatively, you can equivalently run the following command directly in the command line:

musicdl -m NeteaseMusicClient,MiguMusicClient,QQMusicClient -i "{'MiguMusicClient': {'work_dir': 'migu'}, {'NeteaseMusicClient': {'work_dir': 'netease'}, {'QQMusicClient': {'work_dir': 'qq'}}"

If you are a VIP user on a particular music platform, you can pass the cookies from your logged-in web session on that platform to musicdl to improve the quality of song search and downloads. Specifically, for example, if you have a membership on QQMusicClient, your code can be written as follows:

from musicdl import musicdl

your_vip_cookies_with_str_or_dict_format = ""
init_music_clients_cfg = dict()
init_music_clients_cfg['QQMusicClient'] = {'default_search_cookies': your_vip_cookies_with_str_or_dict_format, 'default_download_cookies': your_vip_cookies_with_str_or_dict_format}
music_client = musicdl.MusicClient(music_sources=['NeteaseMusicClient', 'QQMusicClient'], init_music_clients_cfg=init_music_clients_cfg)
music_client.startcmdui()

Of course, you can also achieve the same effect by running the following command directly in the command line:

musicdl -m NeteaseMusicClient,QQMusicClient -i "{'QQMusicClient': {'default_search_cookies': your_vip_cookies_with_str_or_dict_format, 'default_download_cookies': your_vip_cookies_with_str_or_dict_format}}"

If you want to search for more songs on a specific music platform (e.g., QQMusicClient), you can do the following:

from musicdl import musicdl

init_music_clients_cfg = dict()
init_music_clients_cfg['QQMusicClient'] = {'search_size_per_source': 20}
music_client = musicdl.MusicClient(music_sources=['NeteaseMusicClient', 'QQMusicClient'], init_music_clients_cfg=init_music_clients_cfg)
music_client.startcmdui()

Or enter the following in the command line:

musicdl -m NeteaseMusicClient,QQMusicClient -i "{'QQMusicClient': {'search_size_per_source': 20}}"

In this way, you can see up to 20 search results from QQMusicClient.

If you want to use the pyfreeproxy library to automatically leverage free online proxies for music search and download, you can do it as follows:

from musicdl import musicdl

init_music_clients_cfg = dict()
init_music_clients_cfg['NeteaseMusicClient'] = {'search_size_per_source': 1000, 'auto_set_proxies': True, 'proxy_sources': ['QiyunipProxiedSession', 'ProxydailyProxiedSession']}
music_client = musicdl.MusicClient(music_sources=['NeteaseMusicClient'], init_music_clients_cfg=init_music_clients_cfg)
music_client.startcmdui()

The command-line usage is similar:

musicdl -m NeteaseMusicClient -i "{'NeteaseMusicClient': {'search_size_per_source': 1000, 'auto_set_proxies': True, 'proxy_sources': ['QiyunipProxiedSession', 'ProxydailyProxiedSession']}}"

Separating Search and Download Results

You can also call the .search and .download interfaces of musicdl separately to inspect its intermediate results or perform secondary development,

from musicdl import musicdl

# instance
music_client = musicdl.MusicClient(music_sources=['NeteaseMusicClient'])
# search
search_results = music_client.search(keyword='尾戒')
print(search_results)
song_infos = []
for song_infos_per_source in list(search_results.values()):
    song_infos.extend(song_infos_per_source)
# download
music_client.download(song_infos=song_infos)

You can also choose not to use the unified MusicClient interface and instead directly import the definition class for a specific music platform for secondary development. For example, to import the definition class for NeteaseMusicClient:

from musicdl.modules.sources import NeteaseMusicClient

netease_music_client = NeteaseMusicClient()
# search
search_results = netease_music_client.search(keyword='那些年')
print(search_results)
# download
netease_music_client.download(song_infos=search_results)

All supported classes can be obtained by printing MusicClientBuilder.REGISTERED_MODULES, e.g,

from musicdl.modules import MusicClientBuilder

print(MusicClientBuilder.REGISTERED_MODULES)

TIDAL High-Quality Music Download

If you want to download lossless-quality music from TIDAL, you need to make sure that PyAV is available or that FFmpeg is in your environment variables, and then use musicdl as follows:

from musicdl import musicdl

music_client = musicdl.MusicClient(music_sources=['TIDALMusicClient'])
music_client.startcmdui()

Running the above code will automatically open your default browser and prompt you to log in to TIDAL. Once you have successfully logged in, musicdl will automatically capture the tokens from your session to support subsequent music search and download.

If you are running on a remote server where the browser cannot be opened automatically, you can instead copy the URL printed in the terminal and open it in your local browser to complete the login process.

Note that if the account you log in with is not a paid TIDAL subscription, you will still be unable to download the full lossless audio files.

YouTube Music Download

If you want to use musicdl to search for and download music from YouTubeMusicClient, you must have Node.js installed, e.g., on Linux, you can install Node.js using the following script:

#!/usr/bin/env bash
set -e

# Install nvm (Node Version Manager)
curl -fsSL https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash

# Load nvm for this script
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"

# Install and use latest LTS Node.js
nvm install --lts
nvm use --lts

# Print versions
node -v
npm -v

On macOS, you can install Node.js using the following script:

#!/usr/bin/env bash
set -e

# Install nvm (Node Version Manager)
curl -fsSL https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash

# Load nvm for this script
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"

# Install and use latest LTS Node.js
nvm install --lts
nvm use --lts

# Print versions
node -v
npm -v

On Windows (PowerShell), you can install Node.js using the following script:

# Install Node.js LTS via winget
winget install --id OpenJS.NodeJS.LTS -e --source winget

# Print hint for version check
Write-Output ""
Write-Output "Please reopen PowerShell and run:"
Write-Output "  node -v"
Write-Output "  npm -v"

A simple example of searching for and downloading music from YouTubeMusicClient is as follows,

from musicdl import musicdl

music_client = musicdl.MusicClient(music_sources=['YouTubeMusicClient'])
music_client.startcmdui()

WhisperLRC

On some music platforms, it’s not possible to obtain the lyric files corresponding to the audio, e.g, XimalayaMusicClient and MituMusicClient. To handle this, we provide a faster-whisper interface that can automatically generate lyrics for tracks whose lyrics are unavailable for download.

For audio files that have already been downloaded, you can use the following invocation to automatically generate lyrics for the local file,

from musicdl.modules import WhisperLRC

your_local_music_file_path = 'xxx.flac'
WhisperLRC(model_size_or_path='base').fromfilepath(your_local_music_file_path)

The available model_size_or_path, ordered from smallest to largest, are:

tiny, tiny.en, base, base.en, small, small.en, distil-small.en, medium, medium.en, distil-medium.en, large-v1, large-v2, large-v3, large, distil-large-v2, distil-large-v3, large-v3-turbo, turbo

In general, the larger the model, the better the generated lyrics (transcription/translation) will be, but this also means it will take longer to run.

If you want to automatically generate lyric files during the download process, you can set the environment variable ENABLE_WHISPERLRC=True (for example, by running export ENABLE_WHISPERLRC=True). However, this is generally not recommended, as it may cause a single run of the program to take a very long time, unless you set search_size_per_source to 1 and model_size_or_path to tiny.

Of course, you can also directly call .fromurl to generate a lyrics file for a song given by a direct URL:

from musicdl.modules import WhisperLRC

music_file_link = ''
WhisperLRC(model_size_or_path='base').fromurl(music_link)

Scenarios Where Quark Netdisk Login Cookies Are Required

Some websites share high-quality or lossless music files via Quark Netdisk links, for example, MituMusicClient, GequbaoMusicClient, YinyuedaoMusicClient, and BuguyyMusicClient.

If you want to download high-quality or lossless audio files from these music platforms, you need to provide the cookies from your logged-in Quark Netdisk web session when calling musicdl. For example, you can do the following:

from musicdl import musicdl

init_music_clients_cfg = dict()
init_music_clients_cfg['YinyuedaoMusicClient'] = {'quark_parser_config': {'cookies': your_cookies_with_str_or_dict_format}}
init_music_clients_cfg['GequbaoMusicClient'] = {'quark_parser_config': {'cookies': your_cookies_with_str_or_dict_format}}
init_music_clients_cfg['MituMusicClient'] = {'quark_parser_config': {'cookies': your_cookies_with_str_or_dict_format}}
init_music_clients_cfg['BuguyyMusicClient'] = {'quark_parser_config': {'cookies': your_cookies_with_str_or_dict_format}}

music_client = musicdl.MusicClient(music_sources=['MituMusicClient', 'YinyuedaoMusicClient', 'GequbaoMusicClient', 'BuguyyMusicClient'], init_music_clients_cfg=init_music_clients_cfg)
music_client.startcmdui()

Please note that musicdl does not provide any speed-limit bypass for Quark Netdisk. If the cookies you supply belong to a non-VIP Quark account, the download speed may be limited to only a few hundred KB/s.

Apple Music Download

AppleMusicClient works similarly to TIDALMusicClient: if you are not an Apple Music subscriber or you have not manually set in musicdl the cookies (i.e., the media-user-token) from your logged-in Apple Music session in the browser, you will only be able to download a partial segment of each track (usually 30–90 seconds).

If you need to download the full audio and lyrics for each song, you can configure musicdl as follows:

from musicdl import musicdl

cookies = {'media-user-token': xxx}
init_music_clients_cfg = {'AppleMusicClient': {'default_search_cookies': cookies, 'default_download_cookies': cookies, 'search_size_per_source': 10}}
music_client = musicdl.MusicClient(music_sources=['AppleMusicClient'], init_music_clients_cfg=init_music_clients_cfg)
music_client.startcmdui()

It is important to note that to download Apple Music audio files (including decryption) using musicdl, you must properly install GPAC, Bento4 and N_m3u8DL-RE.

For more details, please refer to the official documentation.

⭐ Recommended Projects

• Games: Create interesting games in pure python.
• DecryptLogin: APIs for loginning some websites by using requests.
• Musicdl: A lightweight music downloader written in pure python.
• Videodl: A lightweight video downloader written in pure python.
• Pytools: Some useful tools written in pure python.
• PikachuWeChat: Play WeChat with itchat-uos.
• Pydrawing: Beautify your image or video.
• ImageCompressor: Image compressors written in pure python.
• FreeProxy: Collecting free proxies from internet.
• Paperdl: Search and download paper from specific websites.
• Sciogovterminal: Browse "The State Council Information Office of the People's Republic of China" in the terminal.
• CodeFree: Make no code a reality.
• DeepLearningToys: Some deep learning toys implemented in pytorch.
• DataAnalysis: Some data analysis projects in charles_pikachu.
• Imagedl: Search and download images from specific websites.
• Pytoydl: A toy deep learning framework built upon numpy.
• NovelDL: Search and download novels from some specific websites.

📚 Citation

If you use this project in your research, please cite the repository.

@misc{musicdl2020,
    author = {Zhenchao Jin},
    title = {Musicdl: A lightweight music downloader written in pure python},
    year = {2020},
    publisher = {GitHub},
    journal = {GitHub repository},
    howpublished = {\url{https://github.com/CharlesPikachu/musicdl}},
}

🌟 Star History

☕ Appreciation (赞赏 / 打赏)

WeChat Appreciation QR Code (微信赞赏码)	Alipay Appreciation QR Code (支付宝赞赏码)

📢 WeChat Official Account (微信公众号):

Charles的皮卡丘 (Charles_pikachu)