⚡ mkbrr

Simple. Smart. Fast.

A powerful CLI tool to create, inspect, and modify torrent files. Private by default. Tracker aware.

Overview

Website | Releases

mkbrr (pronounced "make-burr") is a simple yet powerful tool for: - Creating torrent files - Inspecting torrent files - Modifying torrent metadata - Supporting tracker-specific requirements automatically

Key Features: - Fast: Blazingly fast hashing beating the competition - Simple: Easy to use CLI and GUI - Portable: Single binary with no dependencies - Smart: Detects possible missing files when creating torrents for season packs

For detailed documentation and guides, visit mkbrr.com.

Quick Start

Install

For detailed installation instructions, please refer to the Installation section.

Creating a Torrent

# torrents are private by default
mkbrr create path/to/file -t https://example-tracker.com/announce

# public torrent
mkbrr create path/to/file -t https://example-tracker.com/announce --private=false

# Create with randomized info hash
mkbrr create path/to/file -t https://example-tracker.com/announce -e

Table of Contents

• Installation
• GUI
• Usage
• Creating Torrents
• Inspecting Torrents
• Modifying Torrents
• Advanced Usage
• Preset Mode
• Batch Mode
• Tracker-Specific Features
• Incomplete Season Pack Detection
• Performance
• Benchmark Methodology
• Benchmark Results
• Speed Comparison
• Consistency
• Hardware Specifications
• License

Installation

Choose the method that works best for you:

Prebuilt Binaries

Download a ready-to-use binary for your platform from the releases page.

Homebrew (macOS and Linux)

brew install mkbrr

Build from Source

Requirements: See go.mod for Go version.

# Clone the repository
git clone https://github.com/autobrr/mkbrr.git
cd mkbrr

# Install the binary to $GOPATH/bin
make install

# Or install system-wide (requires sudo)
sudo make install    # installs to /usr/local/bin

Go Install

If you have Go installed:

go install github.com/autobrr/mkbrr@latest

# make sure its in your PATH
export PATH=$PATH:$(go env GOPATH)/bin

Docker

# Pull the image
docker pull ghcr.io/autobrr/mkbrr

# Tag it for easier use
docker tag ghcr.io/autobrr/mkbrr mkbrr

# Run with volume mounts for input/output
docker run -v ~/Downloads:/downloads mkbrr mkbrr create /downloads/your-file --output-dir /downloads

For convenience, you can add an alias to your shell configuration:

# Add to your .zshrc or .bashrc
alias mkbrr='docker run -v ~/Downloads:/downloads mkbrr mkbrr'

GUI

mkbrr includes a graphical user interface for those who prefer not to use the command line.

GUI Installation

Download the GUI binary for your platform from the releases page.

Building from Source

# Install Wails CLI (one-time requirement)
make install-wails

# Build GUI for your current platform
make gui-build

# Or build for all platforms
make gui-build-all

The built application will be in gui/build/bin/.

macOS Gatekeeper

The GUI app is not notarized, so macOS will block it by default. Use one of these methods to run it:

Option 1: Remove quarantine attribute (recommended)

xattr -cr /path/to/mkbrr-gui.app

Option 2: Right-click to open 1. Right-click (or Control-click) on the app 2. Select "Open" from the context menu 3. Click "Open" in the dialog

Option 3: System Settings 1. Try to open the app (it will be blocked) 2. Open System Settings → Privacy & Security 3. Click "Open Anyway" next to the mkbrr-gui message

GUI Features

The GUI provides the same core functionality as the CLI with additional usability features:

• Create - Create torrent files with tracker support, presets, and real-time progress tracking with hash rate display
• Inspect - View torrent metadata with searchable, collapsible file tree
• Check - Verify torrent data integrity with detailed results (good/bad/missing pieces)
• Modify - Edit torrent metadata without source files
• Settings - Configure default workers and manage presets (create, edit, delete)

Additional features: - Theme Support - Light, dark, and system theme modes - Tracker Detection - Automatic piece size recommendations based on tracker rules - Form Persistence - Form state is saved across sessions - Preset Management - Full preset CRUD operations with validation

Usage

Creating Torrents

The basic command structure for creating torrents is:

mkbrr create [path] [flags]

For help:

mkbrr create --help

Basic Examples

# Create a private torrent (default)
mkbrr create path/to/file -t https://example-tracker.com/announce

# Create a public torrent
mkbrr create path/to/file -t https://example-tracker.com/announce --private=false

# Create with a comment
mkbrr create path/to/file -t https://example-tracker.com/announce -c "My awesome content"

# Create with a custom output path
mkbrr create path/to/file -t https://example-tracker.com/announce -o custom-name.torrent

# Create with randomized info hash
mkbrr create path/to/file -t https://example-tracker.com/announce -e

# Create a torrent excluding specific file patterns (comma-separated)
mkbrr create path/to/file -t https://example-tracker.com/announce --exclude "*.nfo,*.jpg"

# Create a torrent including only specific file patterns (comma-separated)
mkbrr create path/to/video-folder -t https://example-tracker.com/announce --include "*.mkv,*.mp4"

# Create using a specific number of worker threads for hashing (e.g., 8)
# Experimenting with different values might yield better performance than the default automatic setting.
mkbrr create path/to/large-file -t https://example-tracker.com/announce --workers 8

# Fail if a potentially incomplete season pack is detected
mkbrr create path/to/season-pack -t https://example-tracker.com/announce --fail-on-season-warning

# Create using a name property for the torrent
mkbrr create path/to/file -t https://example-tracker.com/announce --name "Your torrent name"

[!NOTE] The exclude and include patterns feature supports standard glob pattern matching (like * for any number of characters, ? for a single character) and is case-insensitive. Precedence: Inclusion patterns (--include) take precedence. - If --include is used: - A file matching an --include pattern is always kept, even if it also matches an --exclude pattern. - A file not matching any --include pattern is always ignored. - If --include is not used, then only --exclude patterns are considered, and matching files are ignored.

The --workers flag controls the number of concurrent threads used for hashing. - --workers 0 (or omitting the flag) uses automatic logic to determine the optimal number based on your system. - --workers N (where N > 0) uses exactly N threads. While the automatic setting is generally good, you might achieve slightly better performance by manually testing different values for N on your specific hardware and workload.

The --fail-on-season-warning flag makes mkbrr exit with an error if it detects a potentially incomplete season pack instead of just showing a warning.

Inspecting Torrents

View detailed information about a torrent:

mkbrr inspect my-torrent.torrent

Checking Torrents (Verifying Data)

Verify the integrity of local data against a torrent file:

mkbrr check my-torrent.torrent /path/to/downloaded/content

# Verify using a specific number of worker threads (e.g., 4)
mkbrr check my-torrent.torrent /path/to/downloaded/content --workers 4

This shows: - Name and size - Piece information and hash - Tracker URLs - Creation date - Magnet link - File list (for multi-file torrents)

Modifying Torrents

Update metadata in existing torrent files without access to the original content:

# Basic usage
mkbrr modify original.torrent --tracker https://new-tracker.com

# Modify multiple torrents
mkbrr modify *.torrent --private=false

# See what would be changed without making actual changes
mkbrr modify original.torrent --tracker https://new-tracker.com --dry-run

# Modifying the torrent to contain multiple trackers
mkbrr modify original.torrent -t https://first.com -t https://second.com -t https://third.com

# Randomize info hash
mkbrr modify original.torrent -e

# Change the torrent's name property
mkbrr modify original.torrent --name "My new torrent name"

Advanced Usage

Preset Mode

Presets save you time by storing commonly used settings. Great for users who create torrents for the same trackers regularly.

See presets example here.

# Uses the ptp-preset (defined in your presets.yaml file)
mkbrr create -P ptp path/to/file

# Override some preset values
mkbrr create -P ptp --source "MySource" path/to/file

# Override workers count
mkbrr create -P ptp --workers 4 path/to/file

[!TIP] The preset file can be placed in the current directory, ~/.config/mkbrr/, or ~/.mkbrr/. You can also specify a custom location with --preset-file. Presets support both exclude_patterns and include_patterns fields, allowing you to define default or preset-specific file filtering.

Batch Mode

Create multiple torrents at once using a YAML configuration file:

mkbrr create -b batch.yaml

See batch example here.

[!TIP] Batch mode processes jobs in parallel (up to 4 at once) and shows a summary when complete. Batch mode also supports both exclude_patterns and include_patterns fields.

Tracker-Specific Features

mkbrr automatically enforces some requirements for various private trackers so you don't have to:

Piece Length Limits

Different trackers have different requirements: - HDB, BHD, SuperBits: Max 16 MiB pieces - Emp, MTV: Max 8 MiB pieces - GazelleGames: Max 64 MiB pieces

Torrent Size Limits

Some trackers limit the size of the .torrent file itself: - Anthelion: 250 KiB - GazelleGames: 1 MB

[!INFO] When creating torrents for these trackers, mkbrr automatically adjusts piece sizes to meet requirements, so you don't have to.

A full overview over tracker-specific limits can be seen in the documentation.

Incomplete Season Pack Detection

If the input is a folder with a name that indicates that its a pack, it will find the highest number and do a count to look for missing files.

mkbrr create ~/Kyles.Original.Sins.S01.1080p.SRC.WEB-DL.DDP5.1.H.264 -t https://tracker.com/announce/1234567

Files being hashed:
  ├─ Kyles.Original.Sins.S01E01.Business.and.Pleasure.1080p.SRC.WEB-DL.DDP5.1.H.264.mkv (3.3 GiB)
  ├─ Kyles.Original.Sins.S01E02.Putting.It.Back.In.1080p.SRC.WEB-DL.DDP5.1.H.264.mkv (3.4 GiB)
  └─ Kyles.Original.Sins.S01E04.Cursor.For.Life.1080p.SRC.WEB-DL.DDP5.1.H.264.mkv (3.3 GiB)


Warning: Possible incomplete season pack detected
  Season number: 1
  Highest episode number found: 4
  Video files: 3

This may be an incomplete season pack. Check files before uploading.

Hashing pieces... [3220.23 MB/s] 100% [========================================]

Wrote title.torrent (elapsed 3.22s)

Strict Season Pack Validation

By default, mkbrr will show a warning but continue creating the torrent when it detects a potentially incomplete season pack. If you want to fail the operation instead, use the --fail-on-season-warning flag:

# This will exit with an error if missing episodes are detected
mkbrr create ~/Suspicious.Show.S01.1080p.WEB-DL -t https://tracker.com/announce --fail-on-season-warning

[!TIP] The --fail-on-season-warning flag can also be configured in presets and batch files using the fail_on_season_warning field.

Performance

mkbrr is optimized for speed and consistently outperforms other popular torrent creation tools in our benchmarks.

Benchmark Methodology

All tests were performed using hyperfine with 5 runs per tool after a warm-up run. Cache was cleared between runs on the servers, but not on the Macbook.

Benchmark Results