Skip to content

Installation

Jump to bottom
simonefil edited this page Aug 14, 2026 · 6 revisions

Installation

This page covers installation from a downloaded archive. To run a container instead, see Docker; the image already contains every external tool.

1. Install the external tools

RemuxForge drives three external toolsets. It does not bundle them.

Tool Executables RemuxForge calls Used for Must be installed manually
MKVToolNix mkvmerge, mkvextract, mkvpropedit all muxing, track extraction and in-place metadata edits yes
ffmpeg ffmpeg, ffprobe frame extraction for analysis, audio conversion, video re-encoding only on macOS
MediaInfo CLI mediainfo reading track properties and the metadata catalogue yes

ffmpeg and ffprobe are downloaded automatically on Windows x64, Linux x64 and Linux ARM64 when they are not found. This happens in two ways:

  • On demand, using the [ Download ] button in Settings ▸ Tool paths.
  • Automatically during a job. Remux and Split both request ffmpeg with download permitted, so the first run fetches it if it is missing.

The build is stored inside the data directory and the resolved paths are saved to the configuration. If 24bit -> 16bit conversion is requested and the managed build lacks libsoxr, a build that supports it is fetched instead.

On macOS automatic download is disabled. Install ffmpeg manually (brew install ffmpeg) or set the path in Settings ▸ Tool paths.

MKVToolNix and MediaInfo are never downloaded and must always be installed manually. RemuxForge does detect them on PATH, derives mkvextract from the mkvmerge location, and saves what it finds.

Install the MediaInfo CLI package, not the GUI application. The GUI does not provide the mediainfo executable, and Metadata mode cannot scan without it.

Optional Vulkan backend for Deep analysis

Frame-sync, Deep analysis and Speed correction use CPU SIFT by default. Selecting Vulkan under Settings ▸ Advanced settings ▸ Analysis ▸ SIFT backend moves SIFT extraction, descriptor matching and homography RANSAC to the GPU. This requires:

  • a Vulkan 1.2 loader;
  • a Vulkan compute device with timeline semaphore support;
  • a working vendor driver or ICD.

The dialog probes the complete Vulkan pipeline when the backend is selected. If initialization fails, it reports the error and returns the setting to CPU; analysis never silently changes backend during a job.

On Windows, install a current GPU driver from NVIDIA, AMD or Intel. The driver package normally provides both the Vulkan runtime and its ICD.

On Linux, install the Vulkan loader and the driver for the GPU. For Debian or Ubuntu with Intel/AMD Mesa drivers:

sudo apt install libvulkan1 mesa-vulkan-drivers

NVIDIA systems use the Vulkan ICD supplied by the proprietary driver. A Vulkan SDK is not required to run RemuxForge.

macOS has no native Vulkan driver. Install the Vulkan SDK for macOS and its MoltenVK runtime, then make the loader and MoltenVK ICD available to the process as described by the SDK installer. CPU SIFT remains available without MoltenVK.

The Docker image already contains the Vulkan loader and Mesa ICDs. GPU device and driver exposure is configured when the container starts; see Docker.

Installing everything up front is still the simplest route, and it is required on macOS:

# Debian / Ubuntu
sudo apt install mkvtoolnix ffmpeg mediainfo

# Fedora
sudo dnf install mkvtoolnix ffmpeg mediainfo

# Arch
sudo pacman -S mkvtoolnix-cli ffmpeg mediainfo

# macOS (Homebrew)
brew install mkvtoolnix ffmpeg media-info

# Windows (winget)
winget install MoritzBunkus.MKVToolNix
winget install Gyan.FFmpeg
winget install MediaArea.MediaInfo.CLI

On Linux the system locale must be UTF-8, otherwise filenames and track titles containing non-ASCII characters are mangled. Check with locale; if LANG is POSIX or C, set something like LANG=en_US.UTF-8.

2. Download the right archive

Platform Architectures
Windows x64
Linux x64, ARM64
macOS x64, ARM64
Docker x64

Two archives are published per platform on the releases page:

  • RemuxForge.Web: the browser interface, documented throughout this wiki.
  • RemuxForge.Cli: the command-line binary, for scripting. See CLI Reference.

They are independent: install one, the other, or both. They share the same configuration directory, so settings and presets created in the WebUI are picked up by the CLI.

3. Run the WebUI

Windows

RemuxForge.Web.exe

Linux / macOS

chmod +x RemuxForge.Web
./RemuxForge.Web

Then open http://localhost:5000.

The server binds 0.0.0.0, so a machine on your LAN can reach it at http://<host>:5000. There is no authentication. Do not expose the port to the internet. Put it behind a reverse proxy with access control if you need remote access.

On macOS, a downloaded binary is quarantined by Gatekeeper and will refuse to start. Clear the attribute once:

xattr -d com.apple.quarantine RemuxForge.Web

Changing the port

Either an environment variable:

REMUXFORGE_PORT=5050 ./RemuxForge.Web

or an argument, which takes precedence:

./RemuxForge.Web --port 5050

4. Verify the external tools

A missing external tool is the most common cause of an operation producing no result. Open Settings ▸ Tool paths.

Each entry shows a status next to it:

Status Meaning
[OK] found and executable
[NOT FOUND] not on PATH and no valid explicit path set
[CLI NOT FOUND] shown for MediaInfo when the GUI package is installed instead of the CLI package
[ERROR] the path exists but the tool failed to run

The dialog covers mkvmerge, mkvextract, mkvpropedit, ffmpeg, ffprobe, mediainfo and the temp folder used for intermediate files. Paths are auto-detected from PATH at first launch; you only need to fill one in if detection failed or you want to pin a specific build.

ffmpeg has a [ Download ] button, which fetches a build into the data directory and sets both paths. It is disabled on macOS. There is no equivalent for MKVToolNix or MediaInfo; those must be installed manually.

Complete this check before any other configuration. A [NOT FOUND] on mediainfo prevents Metadata mode from scanning. A [NOT FOUND] on ffmpeg is less critical on Windows and Linux, where the first job that needs it downloads it, but on macOS it must be resolved manually.

5. Language and theme

Language offers English and Italian; Theme offers eight terminal-style palettes (Nord, DOS Blue, Matrix, Cyberpunk, Solarized Dark, Solarized Light, Cybergum, Everforest). Both are saved and restored on the next launch. See WebUI Basics.

The data directory

RemuxForge keeps everything persistent in a folder named .remux-forge. By default it is created next to the executable; in the Docker examples it is /data.

Override the parent location with:

REMUXFORGE_DATA_DIR=/path/to/data ./RemuxForge.Web

Layout:

<data dir>/.remux-forge/
├── appsettings.json              all settings: tool paths, audio defaults,
│                                 encoding profiles, UI state, advanced tuning
├── presets/
│   └── metadata/                 metadata presets (*.json) created in the WebUI
├── temp/                         intermediate files (overridable in Tool paths)
├── deepanalysis-diagnostics/     JSON dumps, only when diagnostics are enabled
└── framesync-diagnostics/        JSON dumps, only when diagnostics are enabled

Two consequences:

  • Metadata presets are not free-floating files. The preset dropdown lists the contents of presets/metadata/, and the preset editor writes there. There is no preset path picker in the WebUI. The CLI does take an explicit --preset path.
  • .remux-forge contains all persistent state: settings, presets and profiles. Copy that folder to move or back up an installation.

See Settings Reference for the annotated appsettings.json.

Environment variables

Variable Description Default
REMUXFORGE_PORT WebUI HTTP port 5000
REMUXFORGE_DATA_DIR Parent directory for .remux-forge executable directory
REMUXFORGE_LOG_FILE Write a log file to this path disabled

Enable REMUXFORGE_LOG_FILE when more detail than the in-app log panel is required, for example when reporting a bug.

Updating

Download the new archive, stop the old process, replace the binaries, restart. Do not delete .remux-forge. It holds your settings and presets, and new versions read the existing file, filling in defaults for anything new.

Uninstalling

Delete the extracted folder. Delete .remux-forge as well if you do not want to keep your settings and presets. Nothing is written to the registry or to system directories.

Next

Start here

Using the WebUI

Examples

Reference

Clone this wiki locally