Install

Alchemist ships as a single binary with the web UI embedded. The Docker image bundles FFmpeg — nothing else to install.

Docker (recommended)

Docker Compose:

services:
  alchemist:
    image: ghcr.io/bybrooklyn/alchemist:latest
    container_name: alchemist
    ports:
      - "3000:3000"
    volumes:
      - ./config:/app/config
      - ./data:/app/data
      - /path/to/media:/media
    environment:
      - ALCHEMIST_CONFIG_PATH=/app/config/config.toml
      - ALCHEMIST_DB_PATH=/app/data/alchemist.db
    restart: unless-stopped

docker compose up -d

Open http://localhost:3000. The setup wizard runs on first visit and is only reachable from the local network until the first account is created.

In Docker, Alchemist reads /app/config/config.toml and /app/data/alchemist.db inside the container. Volume syntax is host_path:container_path, so ./config:/app/config stores that same config on the host at ./config/config.toml. If you prefer /data/alchemist/config:/app/config, then the container still uses /app/config/config.toml, backed by /data/alchemist/config on the host.

For GPU passthrough (NVIDIA, Intel, AMD) see GPU Passthrough.

docker run:

docker run -d \
  --name alchemist \
  -p 3000:3000 \
  -v ./config:/app/config \
  -v ./data:/app/data \
  -v /path/to/media:/media \
  -e ALCHEMIST_CONFIG_PATH=/app/config/config.toml \
  -e ALCHEMIST_DB_PATH=/app/data/alchemist.db \
  --restart unless-stopped \
  ghcr.io/bybrooklyn/alchemist:latest

Binary

Download from GitHub Releases. Available for Linux x86_64, Linux ARM64, Windows x86_64, macOS Apple Silicon, and macOS Intel.

Package-manager metadata

Release packaging metadata is generated from this repo’s packaging/ templates during release publication.

• Homebrew formula source lives under packaging/homebrew/
• AUR metadata source lives under packaging/aur/

FFmpeg must be installed separately:

sudo apt install ffmpeg       # Debian / Ubuntu
sudo dnf install ffmpeg       # Fedora
sudo pacman -S ffmpeg         # Arch
brew install ffmpeg           # macOS
winget install Gyan.FFmpeg    # Windows

./alchemist        # Linux / macOS
alchemist.exe      # Windows

Binary installs are not containerized, so the default config path is ~/.config/alchemist/config.toml on Linux/macOS and %APPDATA%\Alchemist\config.toml on Windows. Docker overrides the config path to /app/config/config.toml so it lands in the mounted host directory.

Direct binary users can copy the running executable into a standard or custom directory:

./alchemist --install
./alchemist --install-directory /opt/alchemist/bin

Native runs bind to port 3000 by default. If that port is busy and ALCHEMIST_SERVER_PORT is not set, Alchemist tries the next available port and prints an INFO line with the exact http://127.0.0.1:<port> link. Set ALCHEMIST_SERVER_PORT=<port> to require a specific port.

The About dialog checks the configured update channel (stable, rc, or nightly). Direct Linux/macOS binaries can install signed, verified updates after active jobs drain. Docker, Homebrew, AUR, Windows, source, and unknown installs show guided update instructions instead of replacing files.

From source

For macOS and Linux:

git clone https://github.com/bybrooklyn/alchemist.git
cd alchemist
just install
just build
./target/release/alchemist

Requires Rust 1.88+. Run rustup update stable first.

For Windows local development:

just install-w
just dev

Windows contributor support covers the core install/dev/check path. Broader just release and utility recipes remain Unix-first.

CLI subcommands

alchemist scan /path/to/media
alchemist run /path/to/media
alchemist plan /path/to/media
alchemist plan /path/to/media --json

• scan enqueues matching jobs and exits
• run scans, enqueues, and waits for processing to finish
• plan reports what Alchemist would do without enqueueing jobs

Nightly builds

docker pull ghcr.io/bybrooklyn/alchemist:nightly

Nightly builds publish on every push to master after Rust checks pass. Use :latest for stable releases.

See also

• First Run — setup wizard.
• Hardware Acceleration — NVENC, Quick Sync, VAAPI, AMF, VideoToolbox.
• Alchemist for Jellyfin.
• Alchemist vs Tdarr · Alchemist vs FileFlows.