Skip to main content

Install

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

Docker Compose:

services:
  alchemist:
    image: ghcr.io/bybrooklyn/alchemist:latest
    container_name: alchemist
    ports:
      - "3000:3000"
    volumes:
      - ~/.config/alchemist:/app/config
      - ~/.config/alchemist:/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.

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

docker run:

docker run -d \
  --name alchemist \
  -p 3000:3000 \
  -v ~/.config/alchemist:/app/config \
  -v ~/.config/alchemist:/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

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.85+. 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​