linuxserver/retroarch

linuxserver/retroarch

RetroArch 是一个模拟器、游戏引擎和媒体播放器的前端，通过Docker容器化部署，可在多种计算机和游戏机上运行经典游戏，提供流畅的图形界面。LinuxServer.io团队维护的此镜像包含定期应用更新、用户映射支持、自定义基础镜像及每周安全更新。

支持的架构

该镜像利用Docker清单实现多平台支持，拉取 lscr.io/linuxserver/retroarch:latest 会自动获取对应架构的镜像，也可通过标签指定特定架构：

应用设置

应用可通过以下地址访问：

• [***]

注意事项

• 纯CPU模式：RetroArch会使用LLVMPipe进行菜单渲染，可在设置中配置菜单刷新率或挂载Nvidia GPU。首次使用Nvidia GPU时，需右键桌面并重新启动RetroArch。
• 严格反向代理：默认使用自签名证书（https协议），若反向代理验证证书，需禁用容器证书检查。
• 系统调用限制：现代GUI桌面应用可能受Docker系统调用限制影响，旧内核或libseccomp版本主机可使用 --security-opt seccomp=unconfined 允许相关系统调用。

安全警告

[!WARNING] 此容器提供对主机系统的特权访问，请勿暴露在互联网中，除非已正确配置安全措施。

• HTTPS要求：完整功能需HTTPS，现代浏览器功能（如WebCodecs）不支持不安全的HTTP连接。
• 认证配置：默认无认证，可选 CUSTOM_USER 和 PASSWORD 环境变量启用基本HTTP认证（仅适用于可信局域网）。互联网暴露时，强烈建议使用反向代理（如https://github.com/linuxserver/docker-swag%EF%BC%89%E5%A2%9E%E5%BC%BA%E8%AE%A4%E8%AF%81%E3%80%82
• 终端访问：Web界面包含无密码sudo权限的终端，任何访问GUI的用户可获取容器内root权限，需谨慎配置访问控制。

Selkies基础镜像通用选项

基于https://github.com/linuxserver/docker-baseimage-selkies%EF%BC%8C%E6%94%AF%E6%8C%81%E4%BB%A5%E4%B8%8B%E7%8E%AF%E5%A2%83%E5%8F%98%E9%87%8F%E5%92%8C%E8%BF%90%E8%A1%8C%E9%85%8D%E7%BD%AE%EF%BC%9A

可选环境变量

可选运行配置

语言支持 - 国际化

通过LC_ALL环境变量设置桌面会话语言，例如：

• -e LC_ALL=zh_CN.UTF-8 - 中文
• -e LC_ALL=ja_JP.UTF-8 - 日语
• -e LC_ALL=ko_KR.UTF-8 - 韩语
• -e LC_ALL=ar_AE.UTF-8 - 阿拉伯语
• -e LC_ALL=ru_RU.UTF-8 - 俄语
• -e LC_ALL=es_MX.UTF-8 - 西班牙语（拉丁美洲）
• -e LC_ALL=de_DE.UTF-8 - 德语
• -e LC_ALL=fr_FR.UTF-8 - 法语
• -e LC_ALL=nl_NL.UTF-8 - 荷兰语
• -e LC_ALL=it_IT.UTF-8 - 意大利语

DRI3 GPU加速

挂载渲染设备实现应用/游戏加速，命令： --device /dev/dri:/dev/dri

支持的开源GPU驱动：

DRINODE环境变量可指定特定GPU，aarch64架构需容器内安装对应芯片组驱动。

Nvidia GPU支持

注意：Alpine基础镜像不支持Nvidia。

通过Zink实现OpenGL支持，兼容Nvidia GPU时自动用于硬件加速视频编码（x264enc全帧配置文件），降低CPU负载。

启用Nvidia支持的运行时标志：

Docker Compose配置需先设置Nvidia为默认运行时：

bash
sudo nvidia-ctk runtime configure --runtime=docker --set-as-default
sudo systemctl restart docker

compose.yaml中配置GPU：

yaml
services:
  retroarch:
    image: lscr.io/linuxserver/retroarch:latest
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [compute,video,graphics,utility]

应用管理

PRoot Apps（持久化，推荐）

原生安装包（如apt-get install）在容器重建后不持久，推荐使用https://github.com/linuxserver/proot-apps%E5%AE%89%E8%A3%85%E5%88%B0%E7%94%A8%E6%88%B7%E6%8C%81%E4%B9%85%60$HOME%60%E7%9B%AE%E5%BD%95%EF%BC%9A

bash
proot-apps install filezilla

支持的应用列表见https://github.com/linuxserver/proot-apps?tab=readme-ov-file#supported-apps%E3%80%82

Native Apps（非持久化）

通过https://github.com/linuxserver/docker-mods/tree/universal-package-install mod安装系统原生包（增加启动时间，不持久），compose.yaml配置：

yaml
environment:
  - DOCKER_MODS=linuxserver/mods:universal-package-install
  - INSTALL_PACKAGES=libfuse2|git|gdb

使用方法

docker-compose（推荐）

yaml
---
services:
  retroarch:
    image: lscr.io/linuxserver/retroarch:latest
    container_name: retroarch
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Etc/UTC
    volumes:
      - /path/to/config:/config
    ports:
      - 3000:3000
      - 3001:3001
    shm_size: "1gb"
    restart: unless-stopped

docker cli

bash
docker run -d \
  --name=retroarch \
  -e PUID=1000 \
  -e PGID=1000 \
  -e TZ=Etc/UTC \
  -p 3000:3000 \
  -p 3001:3001 \
  -v /path/to/config:/config \
  --shm-size="1gb" \
  --restart unless-stopped \
  lscr.io/linuxserver/retroarch:latest

参数说明

环境变量文件（Docker secrets）

使用FILE__前缀从文件设置环境变量：

bash
-e FILE__MYVAR=/run/secrets/mysecretvariable

MYVAR值将设为/run/secrets/mysecretvariable文件内容。

应用运行的Umask设置

通过-e UMASK=022覆盖默认umask，详情见umask说明。

用户/组ID

卷挂载时，权限问题可通过指定PUID（用户ID）和PGID（组ID）解决，确保主机卷目录所有者与指定ID一致。使用id your_user查看：

bash
id your_user

输出示例：

text
uid=1000(your_user) gid=1000(your_user) groups=1000(your_user)

Docker Mods

https://img.shields.io/badge/dynamic/yaml?color=94398d&labelColor=555555&logoColor=ffffff&style=for-the-badge&label=retroarch&query=%24.mods%5B%27retroarch%27%5D.mod_count&url=https%3A%2F%2Fraw.githubusercontent.com%2Flinuxserver%2Fdocker-mods%2Fmaster%2Fmod-list.yml]([] "查看此容器可用mods") https://img.shields.io/badge/dynamic/yaml?color=94398d&labelColor=555555&logoColor=ffffff&style=for-the-badge&label=universal&query=%24.mods%5B%27universal%27%5D.mod_count&url=https%3A%2F%2Fraw.githubusercontent.com%2Flinuxserver%2Fdocker-mods%2Fmaster%2Fmod-list.yml]([] "查看通用mods")

支持信息

• 容器运行时Shell访问：

  bash
  docker exec -it retroarch /bin/bash
  

• 实时监控容器日志：

  bash
  docker logs -f retroarch
  

• 容器版本号：

  bash
  docker inspect -f '{{ index .Config.Labels "build_version" }}' retroarch
  

• 镜像版本号：

  bash
  docker inspect -f '{{ index .Config.Labels "build_version" }}' lscr.io/linuxserver/retroarch:latest
  

更新方法

通过Docker Compose

• 更新镜像：

  • 所有镜像：

    bash
    docker-compose pull
    

  • 单个镜像：

    bash
    docker-compose pull retroarch
    

• 更新容器：

  • 所有容器：

    bash
    docker-compose up -d
    

  • 单个容器：

    bash
    docker-compose up -d retroarch
    

• 清理旧镜像：

  bash
  docker image prune
  

通过Docker Run

• 更新镜像：

  bash
  docker pull lscr.io/linuxserver/retroarch:latest
  

• 停止运行中的容器：

  bash
  docker stop retroarch
  

• 删除容器：

  bash
  docker rm retroarch
  

• 使用相同参数重新创建容器（/config目录映射正确则设置保留）

• 清理旧镜像：

  bash
  docker image prune
  

镜像更新通知 - Diun

[!TIP] 推荐使用Diun获取更新通知，不建议使用自动更新容器的工具。

本地构建

bash
git clone https://github.com/linuxserver/docker-retroarch.git
cd docker-retroarch
docker build \
  --no-cache \
  --pull \
  -t lscr.io/linuxserver/retroarch:latest .

跨架构构建（如x86_64构建ARM）：

bash
docker run --rm --privileged lscr.io/linuxserver/qemu-static --reset

然后使用 -f Dockerfile.aarch64 指定架构Dockerfile。

版本历史

• 25.05.25: - 初始版本。