ncm-dl

ncm-dl 是一个基于 uv/Python 的网易云音乐命令行下载工具。

运行时只用 Python 标准库，不依赖第三方包。配置优先读取环境变量，命令行参数可以覆盖环境变量。

用法

cd ~/ncm-dl

uv run ncm-dl search "晴天"
uv run ncm-dl download 186016 --output ~/音乐
uv run ncm-dl url 186016

download 也可以写成 dl：

uv run ncm-dl dl 186016

下载整个网易云歌单并生成 Navidrome 可导入的 M3U：

export MUSIC_U='your_cookie_value'
uv run ncm-dl playlist 你的歌单ID \
  --music-root /opt/navidrome/music \
  --level lossless \
  --navidrome-scan \
  --navidrome-import \
  --navidrome-sudo \
  --sync

先不下载、只确认歌单是否能读取：

uv run ncm-dl playlist 你的歌单ID --dry-run --limit 10

默认会把歌曲下载到：

/opt/navidrome/music/netease/<歌单名-歌单ID>/

并生成：

/opt/navidrome/music/playlists/<歌单名-歌单ID>.m3u

M3U 里的歌曲路径会相对 --music-root 写入，适合 Navidrome 扫描和 navidrome pls import。

如果你的音乐库里已经有按 [...] 标记网易云歌曲 ID 的文件，可以指定复用查找目录，避免重复下载：

uv run ncm-dl playlist 你的歌单ID \
  --music-root /opt/navidrome/music \
  --reuse-dir /opt/navidrome/music/netease

环境变量

支持这些环境变量：

示例：

export MUSIC_U='your_cookie_value'
export OUTPUT_DIR="$HOME/音乐"
export LEVEL=lossless

uv run ncm-dl dl 186016

说明

• 本工具不会把 MUSIC_U 写入磁盘。
• 如果歌曲没有返回可播放 URL，通常需要设置有效网易云账号的 MUSIC_U。
• 网易云返回 MD5 时会默认校验下载文件；只有排查问题时才建议使用 --no-md5。