go-music-dl: a Go music downloader with Web, TUI and desktop modes
A Go-based tool for searching and downloading music across the web. Supports both CLI and web-service modes, with 10+ major built-in platforms including NetEase Cloud Music, QQ Music, Kugou, Bilibili and Qishui Music, plus concurrent multi-source search and lossless-quality resolution.
At a glance
- What is it?
- go-music-dl aggregates search across more than ten music platforms and can resolve lossless-quality audio. It ships as a CLI, a web service, a TUI and a desktop app, under AGPL-3.0.
- Who is it for?
- Adopt go-music-dl if you want a self-hosted web service or CLI that searches several Chinese platforms at once and can pull lossless audio, and if you accept AGPL-3.0 terms. Skip it if you need stable access to a specific platform's paid catalogue, if you cannot run FFmpeg for metadata embedding, or if you want a maintained API contract rather than a scraping tool that tracks upstream changes.
- Can I use it commercially?
- Yes, with strict conditions. AGPL-3.0 is a network copyleft licence: if people use a modified version over a network, for example as a hosted service, you must offer them its source code under the same licence.
- Is it still maintained?
- Yes. The repository received new commits within the last day.
- What is it written in?
- Mainly Go, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- guohuiyuan/go-music-dl6,338 ★ · +1,615
| Repository | 2026-09-23 | 2026-11-15 |
|---|---|---|
| guohuiyuan/go-music-dl | 4.7k | 6.3k |
1,615 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
What go-music-dl searches that a single-platform downloader cannot
A downloader for one service gives you one catalogue and one set of failure modes. go-music-dl is built around the opposite assumption: the README lists NetEase Cloud Music, QQ Music, Kugou, Bilibili, Qishui Music and others, and describes multi-source concurrent search as a core feature. The same query can return results from several platforms at once, and the README says the sources actually available are those listed in the interface.
The audience is narrow but real. It is for people who want a self-hosted service on a home server or NAS, who are comfortable running a Docker container, and who read Chinese. The homepage, screenshots and most of the documentation are Chinese-first, and most supported platforms are Chinese streaming services, alongside Apple Music, Jamendo and JOOX. There is a mobile build, an Android APK with ffmpeg and ffprobe bundled, and an unsigned iOS IPA that the README says users must sign themselves.
Beyond single tracks, the README describes playlist and album search, playlist category browsing across NetEase, QQ, Kugou, Kuwo, Migu, Qianqian, JOOX and Apple Music, and a "my playlists" view for logged-in accounts on NetEase, QQ, Kugou and Qishui. That is a broader scope than most download scripts attempt, and it is also where the project accumulates the most platform-specific code to maintain.
How the Go service, the music-lib dependency and the SQLite index fit together
go.mod shows the shape of the project. The HTTP layer is gin, the terminal interface is charmbracelet's bubbletea and lipgloss, the desktop builds use gioui.org plus webview bindings, and storage is glebarez/sqlite through gorm. Platform logic is not in this repository: it is delegated to github.com/guohuiyuan/music-lib, the same author's library. So go-music-dl is largely a front end over music-lib plus local state.
That local state matters more than it first appears. Local music defaults to data/downloads and can be used as a `local` search source, with pagination, scan snapshots, metadata caching, background refresh and a SQLite index.
Imported files are read for embedded metadata, cover and lyrics first; missing data is filled from same-name files and ffprobe.
Running go-music-dl in Docker and making a first search
The repository ships a Dockerfile and a compose file, so the container path is the shortest one. The image builds the binary with CGO_ENABLED=0, runs Alpine 3.22, installs ffmpeg, and verifies both ffmpeg and ffprobe during the build. The compose file pins the published image, maps port 8080, mounts ./data to /home/appuser/data, and starts the web mode.
services:
music-dl:
image: guohuiyuan/go-music-dl:latest
container_name: music-dl
restart: unless-stopped
ports:
- "8080:8080"
volumes:
- type: bind
source: ./data
target: /home/appuser/data
bind:
create_host_path: true
environment:
- TZ=Asia/Shanghai
command: [ "./music-dl", "web", "--port", "8080", "--no-browser" ]After docker compose up, open http://localhost:8080/music. The README says the web service mounts under /music by default. Search, playback, download and playlist browsing work without logging in; only changing settings or cookies requires an administrator account. On first configuration the startup log prints a Web setup token, which you use to create the administrator account.
If you prefer the terminal, the TUI takes a keyword directly:
./music-dl -k "搜索关键词"To serve the same web UI under a subpath behind a reverse proxy, the README documents --base-path:
./music-dl web --base-path /dlOne practical detail for anyone enabling metadata embedding: downloads use streaming mode by default, which supports Range requests and seeking, and embedding cover and lyrics is an opt-in setting. Turning it on requires FFmpeg, and without it the service skips embedding and returns the original audio.
Where go-music-dl breaks or is the wrong choice
The project's own README documents a live failure: Qishui Music QR login is currently unavailable. Qishui playlist and download features therefore require a manually configured cookie. That is a concrete example of the general risk with this class of tool: platform-side changes silently remove capability, and the fix lives in music-lib, not here.
There are other boundaries. QQ downloads need a valid cookie, and Qishui full tracks need a cookie plus a signature, falling back to public preview clips when the signature is unavailable. Cookies are stored only in the local data directory, and the README warns not to share configuration files publicly; anyone running this on a shared host should treat that file as a secret.
The local music feature has sharp edges too. Deleting a local track is a hard delete: the file is removed from the download directory and the index entry cleared, after a confirmation. Playlists that referenced it keep the entry as invalid, and you can re-point that entry to an online source. And the filename template supports {name}, {artist}, {album}, {source}, {id} and {ext}. Get the template wrong and you will be reorganizing files by hand.
Finally, if what you need is a stable API with a versioned contract, this is the wrong tool. It is a scraper-driven downloader over third-party services, and its correctness depends on those services.
go-music-dl against yt-dlp: aggregation versus extraction
The closest mental comparison is yt-dlp, and the difference is the layer each one works at. yt-dlp extracts streams from a site's own pages and APIs, one extractor per site, and it is used mostly for video platforms and for audio ripped from them. go-music-dl does not extract from a page in that sense; it queries music-lib, which talks to each platform's search and song endpoints, and it adds a web UI, local library management and playlist browsing on top.
That gives go-music-dl two things yt-dlp does not have out of the box: a browser interface and a local music library with a SQLite index, and first-class handling of Chinese music platform login cookies via QR scan for NetEase, QQ Music, Kugou and Bilibili. In the other direction, yt-dlp covers a far wider range of sites and is not tied to Chinese streaming services or to one author's library.
The practical split: if your target is a Chinese music platform and you want a self-hosted web front end with playlists, go-music-dl is the more direct fit. If your target is a video site, or you need one tool that covers many unrelated sources, yt-dlp is the broader instrument.
Licence, maintenance and what upgrading actually costs
go-music-dl is AGPL-3.0. For anyone running it at home that changes nothing. For anyone who modifies it and exposes it as a network service, the AGPL's source-availability obligation is the part to read carefully, and that is a question for a lawyer rather than for this article. The bundled music-lib dependency is a separate module with its own licence, which is worth checking before redistribution.
The maintenance signal is good but should be read precisely. The last push was on 2026-10-19, and v1.1.3 was released the same day, with v1.1.2 on 2026-10-13 and v1.1.1 on 2026-09-17. The repository is not archived. What those dates do not tell you is whether the upstream platforms still behave; a release can ship while a given source is broken, as the unavailable Qishui QR login shows.
Upgrade cost is mostly in local data rather than in the binary. Cookies are kept in the local data directory, and the Docker setup bind-mounts ./data, so a container swap preserves that directory.
Editorial conclusion
Adopt go-music-dl if you want a self-hosted web service or CLI that searches several Chinese platforms at once and can pull lossless audio, and if you accept AGPL-3.0 terms. Skip it if you need stable access to a specific platform's paid catalogue, if you cannot run FFmpeg for metadata embedding, or if you want a maintained API contract rather than a scraping tool that tracks upstream changes. Before deploying, verify that your target sources still respond, that ffmpeg and ffprobe resolve inside the container, and that your download directory is mounted where the service expects it.
Frequently asked questions
What is go-music-dl?
It is a Go music search and download tool that supports Web, TUI and desktop modes, aggregates search across more than ten platforms, and can resolve lossless-quality audio. It is licensed AGPL-3.0.
What is the best music downloader?
There is no single answer, and the README makes no such claim. go-music-dl fits cases where you want a self-hosted web service or CLI that searches several Chinese platforms at once and can download lossless audio; a tool aimed at other sites or other formats would be a different choice.
Why is Google music no longer available?
This question is about Google Play Music, not about go-music-dl, which does not cover Google's service. For go-music-dl, the README does document one source that is currently unavailable: Qishui Music's QR login is currently unavailable, so it needs a manually configured cookie.
Is Go-Go Music still around?
This question refers to Go-Go music, a genre, and not to the go-music-dl project, which the project does not address. The project itself is not archived: the last push was on 2026-10-19, and v1.1.3 was released the same day.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/guohuiyuan-go-music-dl)Star history chart for your README
[](https://hysenlabs.com/projects/guohuiyuan-go-music-dl)Was this useful?