Transmission 配置文件路径:Windows、Linux、macOS、Docker 一张表查清
简答:最常见的路径是 Windows Qt 客户端的 %LOCALAPPDATA%\transmission\settings.json、Linux 用户 daemon 的 ~/.config/transmission-daemon/settings.json,以及 Debian 服务入口 /etc/transmission-daemon/settings.json。修改前先确认运行方式并停止对应进程;Docker 则先用 docker inspect 找主机挂载到容器 /config 的目录。
定义:Transmission 配置文件是保存客户端或 daemon 设置的 JSON 文件,常见文件名为 settings.json,实际位置由系统、运行模式、环境变量、启动参数或容器挂载决定。
先看路径对照表:Transmission 配置文件在哪里
如果你只是想找到 settings.json,先按实际运行方式查表。上游文档把 Windows Qt 客户端、Windows daemon、Linux 图形客户端、Linux daemon 和 macOS 的配置方式分开说明;如果你改完文件,重启后内容又恢复,优先怀疑改错运行方式或程序仍在运行。可先查看Transmission 官方配置文件说明。
| 场景 | 优先检查的位置 | 核对要点 |
|---|---|---|
| Windows Qt 图形客户端 | %LOCALAPPDATA%\transmission\settings.json | 当前登录用户的本地应用数据目录。 |
| Windows daemon | %LOCALAPPDATA%\transmission-daemon\settings.json | 如果由服务账户运行,%LOCALAPPDATA% 可能对应服务账户目录。 |
| Linux GTK/Qt 客户端 | ~/.config/transmission/settings.json | 适用于当前用户运行的图形客户端。 |
| Linux 用户自行运行 daemon | ~/.config/transmission-daemon/settings.json | 如果使用了 -g、--config-dir 或环境变量,应以启动参数为准。 |
| Debian 12 打包的 transmission-daemon | /etc/transmission-daemon/settings.json | Debian 12 的配置文件入口;运行目录参数指向 /var/lib/transmission-daemon/info。 |
| macOS 图形客户端 | ~/Library/Application Support/Transmission 与 ~/Library/Preferences/org.m0k.transmission.plist | 当前官方配置说明列出应用设置和每个任务资料,没有把 Linux 风格路径列为 macOS 默认项。 |
| Docker | 以镜像规定的容器目录为准;LinuxServer.io 镜像使用 /config | 主机路径由 volume 映射决定,不能直接把容器路径当成主机路径。 |
先试这一步:确认 Transmission 是图形客户端、daemon、Debian 服务还是容器;不要只搜索文件名,因为同一台机器可能同时存在多个 settings.json。
修改不生效先做 5 步:停止、备份、确认、修改、复查
- 确认运行方式:区分 Windows Qt、Linux 图形客户端、用户 daemon、Debian 服务和 Docker。
- 确认实际配置目录:检查
TRANSMISSION_HOME、XDG_CONFIG_HOME、启动参数中的-g/--config-dir,以及 Docker 的主机挂载源。 - 先停止对应进程或容器:官方 daemon 文档说明,daemon 退出时可能覆盖正在编辑的配置;Debian Wiki 和 LinuxServer.io 镜像文档也要求先停止再改。
- 备份原文件:至少复制一份
settings.json,不要直接删除。 - 修改并复查:确认 JSON 的引号、逗号、数字和布尔值格式正确,重新启动后再检查文件是否保留修改。
这套流程适用于端口、RPC、下载目录、白名单和限速等配置。不要把“能找到 settings.json”误认为“找到了当前正在使用的 settings.json”。
如果是用户自行运行的 daemon,可先用 shell 查看默认文件:
printf '%s\n' "$HOME/.config/transmission-daemon/settings.json"
ls -l "$HOME/.config/transmission-daemon/settings.json"daemon 支持用 -g 指定配置目录,参数定义可查看Transmission daemon 参数源码说明。
Windows:Qt 客户端和 daemon 要分开找
Windows 官方配置说明列出两个不同目录:Qt 客户端使用 %LOCALAPPDATA%\transmission,daemon 使用 %LOCALAPPDATA%\transmission-daemon。因此,Windows 上最常见的错误是打开了图形客户端的文件,却实际修改了后台 daemon 的配置。
- 按
Win+R打开运行框,输入%LOCALAPPDATA%。 - 分别检查
transmission和transmission-daemon两个目录。 - 搜索
settings.json后,结合所在目录、文件修改时间和当前运行程序判断目标文件。 - 如果 Transmission 作为 Windows 服务运行,确认服务使用的账户;官方文档指出,服务上下文的
%LOCALAPPDATA%可能不是当前登录用户的目录。
Windows 路径中的斜杠建议统一使用反斜杠,便于在资源管理器和命令行中直接核对。目录中还可能存在 stats.json、torrents 和 resume 等资料,迁移时不要只按文件名做判断。
Linux:用户 daemon、图形客户端和 Debian 服务不是同一路径
Linux 图形客户端默认查看 ~/.config/transmission/settings.json,用户自行运行的 daemon 默认查看 ~/.config/transmission-daemon/settings.json。上游文档同时提醒,部分发行版的启动脚本会使用不同位置,因此 Debian 打包服务应优先按 Debian 自己的文件和启动配置核对。
用户自行运行的 daemon
如果启动命令中有 -g 或 --config-dir,指定目录优先级高于默认目录。例如:
transmission-daemon -g /path/to/config也可以检查环境变量。官方环境变量说明指出,TRANSMISSION_HOME 可以覆盖 Transmission 的默认设置目录;Unix 系统还会受 XDG_CONFIG_HOME 影响。详见Transmission 官方环境变量说明。
Debian 12 打包的 transmission-daemon
Debian Wiki 将服务配置入口写为 /etc/transmission-daemon/settings.json,并说明 daemon 运行时直接编辑可能在退出时被覆盖。Debian 12 的打包文件还显示:启动配置把 CONFIG_DIR 设为 /var/lib/transmission-daemon/info,并通过 --config-dir $CONFIG_DIR 启动;另一个打包链接把 /var/lib/transmission-daemon/.config/transmission-daemon/settings.json 链接到 /etc/transmission-daemon/settings.json。因此,Debian 12 下通常应把 /etc/transmission-daemon/settings.json 当作真实配置入口,把 /var/lib/transmission-daemon/info 当作运行目录和配置链接所在位置。
可用下面的命令确认本机关系:
ls -l /var/lib/transmission-daemon/.config/transmission-daemon/settings.json
readlink -f /var/lib/transmission-daemon/.config/transmission-daemon/settings.json
ls -ld /var/lib/transmission-daemon/info不要对 /etc/transmission-daemon/settings.json 执行 readlink -f 后再据此判断它是软链接;在 Debian 12 这个入口通常就是目标文件本身。本文的软链接关系以 Debian 12 打包文件为例,新版 Debian 的打包布局需在对应版本资料中重新核实。
停止、备份、修改、启动示例:
sudo systemctl stop transmission-daemon
sudo cp /etc/transmission-daemon/settings.json /etc/transmission-daemon/settings.json.bak
sudoedit /etc/transmission-daemon/settings.json
sudo systemctl start transmission-daemon如果系统没有使用 systemd,不要直接照搬上面的服务命令;先确认本机的服务管理方式。
macOS:当前官方默认项不等于 Linux 的 settings.json 路径
当前 Transmission 官方配置文件说明对 macOS 列出的默认项包括 $HOME/Library/Application Support/Transmission 的每个任务资料,以及 $HOME/Library/Preferences/org.m0k.transmission.plist 的应用设置。官方环境变量说明还指出,macOS 版本在未设置 TRANSMISSION_HOME 时,会使用 $HOME/Library/Application Support/Transmission 查找设置。
因此,macOS 图形客户端找不到 Linux 风格的 ~/.config/transmission-daemon/settings.json 并不奇怪。当前官方资料没有把一个独立的 macOS daemon 默认 settings.json 路径明确列出;如果你运行的是命令行 daemon,应按以下顺序核对:
- 检查启动命令是否设置了
-g/--config-dir。 - 检查当前 shell 或服务环境中的
TRANSMISSION_HOME。 - 检查
~/Library/Application Support/Transmission。 - 只有确认实际运行方式使用 JSON 配置文件后,才编辑对应的
settings.json。
这比直接套用 Linux 路径更可靠;若你的 macOS 安装方式提供了独立启动脚本或服务文件,应以该文件实际传入的配置目录为准。
Docker:先看挂载关系,再找主机上的 settings.json
Docker 没有适用于所有镜像的统一主机路径。以 LinuxServer.io 的 Transmission 镜像为例,容器内配置目录是 /config,镜像文档明确说明 settings.json 位于该目录;主机目录由 volume 的外部路径决定。详见LinuxServer.io Transmission 镜像文档。
先查看容器的挂载关系:
docker inspect transmission --format '{{range .Mounts}}{{println .Source " -> " .Destination}}{{end}}'如果输出类似 /srv/transmission/data -> /config,则主机上的配置文件通常在该外部目录内。可继续执行:
sudo find /srv/transmission/data -name settings.json -type f -print也可以在容器内查找:
docker exec -it transmission sh -c 'find /config -name settings.json -type f -print'修改示例应使用真实编辑命令,不能把中文说明当成 shell 命令:
docker stop transmission
cp /srv/transmission/data/settings.json /srv/transmission/data/settings.json.bak
sudoedit /srv/transmission/data/settings.json
docker start transmission上面的 /config 和 /srv/transmission/data 只对应这个镜像示例。其他镜像可能使用不同的内部目录、环境变量或启动脚本,必须按对应镜像说明确认。
备份与迁移:只复制 settings.json 可能不够
如果只是修改端口、RPC 或下载目录,备份 settings.json 通常是第一步;如果要迁移整套 Transmission,还应评估配置目录中的其他内容。官方配置文件说明列出了 stats.json、锁文件、torrents/、resume/ 和 blocklists/ 等资料。
- 只改参数:停止对应程序,复制
settings.json,修改后重新启动。 - 迁移任务:同时检查
torrents、resume和实际下载数据目录。 - 迁移 Debian 服务:备份
/etc/transmission-daemon/settings.json,并记录/var/lib/transmission-daemon/info的服务运行关系。 - 迁移 Docker:备份主机映射到
/config的整个目录,并保留 Compose 或 docker run 中的 volume 参数。
配置和备份中可能包含 RPC 认证、白名单、用户名、路径和网络信息。分享配置片段或日志前,应删除密码、访问令牌、用户名、内网地址和真实下载路径。
常见问题
Transmission 的 settings.json 是什么文件?
它是保存 Transmission 客户端或 daemon 设置的 JSON 文件,可能涉及端口、RPC、下载目录、限速和白名单。实际位置取决于系统、运行方式和自定义配置目录。
Windows 下 Transmission 配置文件在哪里?
Qt 图形客户端优先检查 %LOCALAPPDATA%\transmission\settings.json;daemon 优先检查 %LOCALAPPDATA%\transmission-daemon\settings.json。作为服务运行时,还要确认服务账户。
Linux 下 /etc/transmission-daemon/settings.json 是通用路径吗?
不是。它主要对应 Debian 等发行版的打包 daemon。用户自行运行的 daemon 通常先看 ~/.config/transmission-daemon;Debian 12 还应检查 /var/lib/transmission-daemon/info 和对应的软链接。
Debian 12 的 settings.json 软链接方向是什么?
以 Debian 12 打包文件为例,/var/lib/transmission-daemon/.config/transmission-daemon/settings.json 是链接位置,指向 /etc/transmission-daemon/settings.json;/etc 下通常是配置入口和目标文件。可用 ls -l 与 readlink -f 检查。
为什么修改 settings.json 后又恢复原样?
常见原因是 Transmission 仍在运行,daemon 退出时把内存中的设置写回文件;也可能是改错了客户端、服务账户、Docker 主机挂载路径或自定义配置目录。应先停止、备份,再修改。
Docker 里的 Transmission 配置文件在哪里?
没有统一的主机路径。以 LinuxServer.io 镜像为例,容器内配置目录是 /config,主机目录由 volume 映射决定;先用 docker inspect 查看映射,再到主机目录查找 settings.json。
macOS 上为什么找不到 settings.json?
当前官方资料列出的 macOS 默认项是 Application Support/Transmission 和 org.m0k.transmission.plist,没有把 Linux 风格的 ~/.config/transmission-daemon/settings.json 列为 macOS 默认项。应检查 -g、TRANSMISSION_HOME 和实际启动方式。
可以直接删除 settings.json 让 Transmission 自动生成吗?
不建议直接删除。先停止程序并备份,再考虑把文件重命名为 settings.json.bak;否则 RPC、端口、下载目录和白名单等设置可能丢失。
相关阅读
参考资料
- Transmission 官方 Configuration-Files.md:Windows、Linux、macOS 默认配置位置与 settings.json 说明
- Transmission 官方 Environment-Variables.md:TRANSMISSION_HOME、XDG_CONFIG_HOME 与 macOS 配置目录
- Transmission daemon 参数源码:-g/--config-dir 配置目录参数
- Transmission 官方 Headless Usage:daemon 默认配置文件与停止后修改说明
- Debian Wiki:transmission-daemon 配置入口与运行中修改会被覆盖的说明
- Debian Sources:Debian 12 transmission-daemon 软链接定义
- Debian Sources:Debian 12 CONFIG_DIR 与 --config-dir 启动参数
- LinuxServer.io 官方 Transmission 镜像文档:/config、挂载关系与停止容器后修改配置