Install with Docker

MovieClaw ships as one official image, movieclaw/movieclaw, and everything runs in a single container. There's no separate database or Redis to set up, and a TMDB key is already included. The same tag works on x86_64 and ARM64. Using a NAS with a GUI? Follow the guide for Synology, QNAP, or Unraid.

What you need

• A machine with Docker and Docker Compose (Docker Desktop on Windows and macOS).
• Two folders: where your media lives, and where your download client saves files. Both must be writable, since importing and upgrades move files around.

Step 1: Create docker-compose.yml

Make a new folder (say, movieclaw), create docker-compose.yml inside it, and paste this in:

services:
  movieclaw:
    image: movieclaw/movieclaw:latest
    container_name: movieclaw
    init: true
    ports:
      # Host port on the left. If 3000 is taken, change the left side (e.g. "8096:3000")
      - "3000:3000"
    volumes:
      # All runtime data. Back up this folder (it includes the hidden .secret_key file)
      - ./data:/app/data
      - /srv/media:/media  # ← your media folder
      - /srv/downloads:/downloads  # ← your download client's save folder
    environment:
      - TZ=Europe/London  # ← your time zone
    restart: unless-stopped

Step 2: Point it at your folders

One rule to remember: the path left of the colon is a folder on your machine, and the path on the right is what MovieClaw sees inside the container. Whenever the web app asks for a path, use the right-hand one (/media, /downloads). Got more drives? Add a line for each, like - /mnt/disk2/movies:/movies.

Step 3: Start it

From that folder, run:

docker compose up -d

The first start takes about ten seconds on a fast machine, or a minute or two on a slower NAS. Until then, the page says it's connecting, which is normal. Once docker logs movieclaw prints 前端反代 已就绪 ("frontend proxy ready"), you're up.

Step 4: Open the web app

Go to http://<host-ip>:3000 and follow the wizard to create your admin account. Then set up your library, download client, and trackers: see First-time setup.

Prefer a one-liner?

docker run -d --name movieclaw --init -p 3000:3000 \
  --restart unless-stopped \
  -e TZ=Europe/London \
  -v "$(pwd)/data:/app/data" \
  -v /srv/media:/media \
  -v /srv/downloads:/downloads \
  movieclaw/movieclaw:latest

Updating

Day-to-day updates happen in the web app under Settings → Updates & maintenance (更新与维护). It downloads a package of a few megabytes, survives container rebuilds, and can be rolled back from the same page. You only need a new image when the release notes say so:

docker compose pull && docker compose up -d

Troubleshooting

Port 3000 is already in use

Change the left side of ports, e.g. "8096:3000", and open http://<host-ip>:8096 instead. Leave the container side at 3000.

Metadata fails and the logs say TMDB is unreachable

Set a proxy or mirror under Settings → Network (网络), then use the connectivity test on that page.

PUID / PGID?

Not supported. The container runs as root, so files in data are owned by root. Your media folders must be writable.

Library on an SMB / NFS share

Turn off real-time file watching when you add the library. File events over network shares aren't reliable, so scheduled and manual scans work better.

Backups

Back up the data folder and you're covered. It includes a hidden .secret_key file, so make sure your backup tool keeps dotfiles.