musicdl: a pure-Python downloader with dozens of music clients behind one interface

The problem musicdl solves: one interface over many music platforms

Every music service exposes its own search endpoint, its own result schema and its own download URL format. Writing a collector for a music information retrieval experiment, or a personal library tool, means writing one adapter per service. musicdl's answer is to put all of those adapters behind a single Python class and a single command line entry point, so the calling code does not change when you switch from Kugou to TIDAL. The README positions the project for personal listening workflows, collection management, and academic or educational uses such as music information retrieval, data collection and reproducible research. The supported-client table lists platforms in Greater China (Bilibili, Bodian, 5SING, Kugou and others) alongside international ones, and marks each row with whether search and download are supported. That table is the honest starting point for evaluating the project: it tells you which platforms are first-class and which are not. It does not tell you how often each client breaks, and the release notes suggest the answer varies a lot by platform.

How the client architecture works

The repository layout shows the mechanism. Each platform lives in its own file under musicdl/modules/sources, for example bilibili.py, bodian.py and fivesing.py, and the README links each table row to its source file. That means a platform is added or repaired by editing one module rather than touching a shared abstraction, which is why the project can carry dozens of them. The top-level package also contains an mcp/ directory and a scripts/ directory, and setup.py declares a console script entry point named musicdl that maps to musicdl.musicdl:MusicClientCMD, so the CLI and the library share the same client code. Dependencies in requirements.txt hint at what the clients actually do at runtime: requests and curl-cffi for HTTP, pycryptodomex and cryptography for request signing, pywidevine for DRM-related handling, ytmusicapi and m3u8 for YouTube-style sources, mutagen and tinytag for reading audio metadata, and rich, prettytable and prompt-toolkit for terminal output. The package_data line in setup.py ships files matching musicdl/modules/wvds/*.wvd, which indicates that Widevine device files are packaged with the distribution. The README does not explain what those files are used for or how they are obtained, and that is a gap worth noting before you rely on the DRM path.

Installing musicdl and running a first search

The README points to PyPI for the package, and the Makefile shows the source install path. The simplest route is pip, which pulls the pinned dependencies listed in requirements.txt. The project's own Makefile uses setup.py, so both routes exist.

pip install musicdl

After installing, the console script declared in setup.py is available as musicdl. Running it without arguments is the way to see the interactive command interface built with prompt-toolkit and rich.

musicdl

setup.py also lists requirements-optional.txt as a separate file at the repository root, which suggests some functionality is not installed by default. The README does not document which features that file enables, so treat the default install as the supported path until you read that file. If you prefer the source route, the Makefile provides targets that call setup.py directly.

make install

For library use, the README links per-platform code snippets in the client table rather than showing one canonical example, so the exact constructor arguments for a given client should be read from its linked source file (for example bilibili.py or bodian.py) rather than assumed.

The maintenance model is the main risk

The release notes are unusually candid about what maintenance means here. The 2026-09-08 release says it regularly maintains the APIs for Kugou Music, NetEase Cloud Music, Soda Music and QQ Music, fixing or deprecating endpoints that no longer function. The 2026-09-02 release says YouTube's native API had become completely unusable and the YouTube client was fully refactored with a large amount of unnecessary code removed. That is the real failure mode: a client does not degrade gracefully, it stops working when the upstream service changes, and the fix arrives as a new package release. If you pin musicdl and freeze your environment, you inherit a working snapshot that will silently rot as the platforms move. The last push to the repository was on 2026-09-12, and the repository is not archived, so the project is being touched. But the release cadence is driven by upstream breakage, not by a roadmap you can plan around. The README does not document a rollback procedure or a compatibility policy for old versions.

Where musicdl is the wrong tool

The disclaimer is explicit: commercial use is prohibited, and access to paid, subscription or otherwise restricted content must go through authorized channels. Using the software to circumvent paywalls, DRM or licensing restrictions is prohibited. That rules musicdl out for any product that monetizes downloads, and it means the Widevine-related dependencies are not a licence to bypass access controls. The second case is scale. This is a downloader that talks to public web endpoints, not a licensed distribution channel, so it is a poor foundation for anything that needs stable throughput or an SLA. The third case is a single-platform need: if you only ever pull from one service, the value of the shared interface disappears, and you carry the whole dependency set (cryptography, pywidevine, nodejs-wheel, av, and the rest) for one adapter. The README also does not describe rate limiting or retry behaviour, so a bulk collection job is something you would have to throttle yourself.

How musicdl differs from Glomatico-style downloaders

The related searches surface Glomatico and Spotify-downloader, which represent a different design. Those projects are typically built around a single service and its authentication flow, and they tend to be distributed as standalone command line tools or containers. musicdl inverts that: it is a library first, with a CLI bolted on through the console script entry point, and its breadth comes from keeping each platform in an isolated module under musicdl/modules/sources. The practical difference is what you do when something breaks. With a single-service tool you wait for that tool's maintainer. With musicdl you can open the one module for the broken platform, read its request code, and patch it yourself without understanding the other clients. The cost is that no single client gets the depth of attention a dedicated tool gives it, and the release notes show the result: platforms are patched in batches, and some endpoints are deprecated rather than fixed.

Licence, packaging and upgrade cost

The licence situation needs care. The repository's LICENSE file exists, but the metadata reports NOASSERTION, meaning the licence could not be classified automatically. The README badge says PolyForm-Noncommercial-1.0.0, and setup.py carries the classifier "License :: Free for non-commercial use". Those three signals point the same direction but they are not a substitute for reading the LICENSE file yourself; this is a description of what the repository states, not legal advice. The packaging is conventional setuptools with find_packages, include_package_data and a single console script, so upgrades are ordinary pip upgrades. The real upgrade cost is not the install, it is the re-testing: because clients are fixed in response to upstream changes, a version bump can change behaviour for a platform you depend on without any change to your own code. Pin the version, keep a note of which client modules you use, and re-run your own checks after each bump. The README does not publish a changelog beyond the What's New entries, so the release notes are the only signal about which clients moved.

Editorial conclusion

Adopt musicdl if you need programmatic search and download across many Chinese and international platforms and can tolerate a client that is patched whenever a service changes its endpoints. Do not adopt it for commercial products: the licence badge reads PolyForm-Noncommercial-1.0.0, setup.py classifies it as free for non-commercial use, and the README prohibits redistribution or bundling. Before building on it, check that the specific client you need still works, since the release notes record endpoints that were fixed or deprecated, and confirm which files the repository actually ships.

Frequently asked questions

Official sources

1. CharlesPikachu/musicdl on GitHub
2. Issues
3. Project website
4. README
5. Releases