ncm-dl 0.1.2

Small uv/Python CLI for downloading NetEase Cloud Music tracks.

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

环境变量

支持这些环境变量：

变量	作用
MUSIC_U	网易云 MUSIC_U cookie，用于付费/VIP/无损歌曲。
OUTPUT_DIR	默认下载目录。
LEVEL	默认音质：standard、higher、exhigh、lossless、hires。默认 exhigh。
LIMIT	默认搜索结果数量。默认 10。
OVERWRITE	设为 1、true 或 yes 时，默认覆盖同名文件。
CHECK_MD5	设为 0、false 或 no 时，默认关闭 MD5 校验。
NCM_REUSE_DIR	playlist 命令按网易云歌曲 ID 查找已有文件的目录。默认 <music-root>/netease。
NAVIDROME_MUSIC_ROOT	playlist 命令默认音乐库根目录。默认 /opt/navidrome/music。
NAVIDROME_BIN	playlist --navidrome-import 使用的 Navidrome 可执行文件。默认 navidrome。
NAVIDROME_CONFIG	Navidrome 配置文件。默认 /etc/navidrome/navidrome.toml。
NAVIDROME_USER	导入歌单所属的 Navidrome 用户。默认第一个管理员。
NAVIDROME_SUDO	设为 1、true 或 yes 时，导入步骤使用 sudo navidrome。
NAVIDROME_SYNC	设为 1、true 或 yes 时，导入时加 --sync。
NCM_TIMEOUT	下载超时时间，单位秒。默认 60。
NCM_USER_AGENT	自定义请求 User-Agent。

示例：

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。