⚡ 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
• 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
• 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 tap autobrr/mkbrr
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'

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

[!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

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

Speed Comparison

Consistency

Besides raw speed, mkbrr shows more consistent performance between runs, with standard deviation percentages between 0.25-3.7% across platforms compared to much higher variances for other tools (up to 39%). This predictable performance is particularly noticeable on mechanical storage where other tools showed wider fluctuations.

Hardware Specifications

Leaseweb Dedicated Server (SSD)

• CPU: Intel Xeon E-2274G @ 4.00GHz
• RAM: 32GB
• Storage: 1 × SAMSUNG MZQL21T9HCJR-00A07 1.92TB SSD

Hetzner Dedicated Server (HDD)

• CPU: AMD Ryzen 5 3600 (12) @ 4.71GHz
• RAM: 64GB
• Storage: 4 × TOSHIBA MG08ACA16TEY in RAID0

Macbook Pro M4

• CPU: Apple M4
• RAM: 16GB
• Storage: 512GB NVME

Full results

hyperfine --warmup 1 --runs 5 \
  --setup 'sudo sync && sudo sh -c "echo 3 > /proc/sys/vm/drop_caches"' \
  --prepare 'sudo sync && sudo sh -c "echo 3 > /proc/sys/vm/drop_caches" && rm -f /home/user/Show.S01.DL.1080p.WEB.H264-GROUP.torrent' \
  'mkbrr create /home/user/torrents/qbittorrent/Show.S01.DL.1080p.WEB.H264-GROUP' \
  'mktorrent /home/user/torrents/qbittorrent/Show.S01.DL.1080p.WEB.H264-GROUP' \
  'torrenttools create --threads 8 ~/torrents/qbittorrent/Show.S01.DL.1080p.WEB.H264-GROUP' \
  'torf --threads 8 /home/user/torrents/qbittorrent/Show.S01.DL.1080p.WEB.H264-GROUP'

Benchmark 1: mkbrr create /home/user/torrents/qbittorrent/Show.S01.DL.1080p.WEB.H264-GROUP
  Time (mean ± σ):      7.244 s ±  0.018 s    [User: 31.245 s, System: 7.554 s]
  Range (min … max):    7.225 s …  7.270 s    5 runs

Benchmark 2: mktorrent /home/user/torrents/qbittorrent/Show.S01.DL.1080p.WEB.H264-GROUP
  Time (mean ± σ):     45.407 s ±  0.163 s    [User: 36.495 s, System: 4.983 s]
  Range (min … max):   45.135 s … 45.539 s    5 runs

Benchmark 3: torrenttools create --threads 8 ~/torrents/qbittorrent/Show.S01.DL.1080p.WEB.H264-GROUP
  Time (mean ± σ):      9.074 s ±  0.093 s    [User: 29.248 s, System: 5.228 s]
  Range (min … max):    8.908 s …  9.122 s    5 runs

Benchmark 4: torf --threads 8 /home/user/torrents/qbittorrent/Show.S01.DL.1080p.WEB.H264-GROUP
  Time (mean ± σ):      8.854 s ±  0.077 s    [User: 25.829 s, System: 5.136 s]
  Range (min … max):    8.771 s …  8.937 s    5 runs

Summary
  'mkbrr create /home/user/torrents/qbittorrent/Show.S01.DL.1080p.WEB.H264-GROUP' ran
    1.22 ± 0.01 times faster than 'torf --threads 8 /home/user/torrents/qbittorrent/Show.S01.DL.1080p.WEB.H264-GROUP'
    1.25 ± 0.01 times faster than 'torrenttools create --threads 8 ~/torrents/qbittorrent/Show.S01.DL.1080p.WEB.H264-GROUP'
    6.27 ± 0.03 times faster than 'mktorrent /home/user/torrents/qbittorrent/Show.S01.DL.1080p.WEB.H264-GROUP'

hyperfine --warmup 1 --runs 5 \
  --setup 'sudo sync && sudo sh -c "echo 3 > /proc/sys/vm/drop_caches"' \
  --prepare 'sudo sync && sudo sh -c "echo 3 > /proc/sys/vm/drop_caches" && rm -f /home/user/mkbrr/Show.S01.1080p.SRC.WEB-DL.DDP5.1.H.264-GRP.torrent' \
  'mkbrr create ~/torrents/qbittorrent/tv/Show.S01.1080p.SRC.WEB-DL.DDP5.1.H.264-GRP' \
  'mktorrent ~/torrents/qbittorrent/tv/Show.S01.1080p.SRC.WEB-DL.DDP5.1.H.264-GRP' \
  'torrenttools create --threads 12 ~/torrents/qbittorrent/tv/Show.S01.1080p.SRC.WEB-DL.DDP5.1.H.264-GRP' \
  'torf --threads 12 ~/torrents/qbittorrent/tv/Show.S01.1080p.SRC.WEB-DL.DDP5.1.H.264-GRP'

Benchmark 1: mkbrr create ~/torrents/qbittorrent/tv/Show.S01.1080p.SRC.WEB-DL.DDP5.1.H.264-GRP
  Time (mean ± σ):     41.022 s ±  0.979 s    [User: 13.691 s, System: 6.747 s]
  Range (min … max):   39.938 s … 42.467 s    5 runs

Benchmark 2: mktorrent ~/torrents/qbittorrent/tv/Show.S01.1080p.SRC.WEB-DL.DDP5.1.H.264-GRP
  Time (mean ± σ):     68.168 s ± 26.654 s    [User: 17.934 s, System: 6.543 s]
  Range (min … max):   39.268 s … 97.574 s    5 runs

Benchmark 3: torrenttools create --threads 12 ~/torrents/qbittorrent/tv/Show.S01.1080p.SRC.WEB-DL.DDP5.1.H.264-GRP
  Time (mean ± σ):     47.968 s ± 10.552 s    [User: 7.052 s, System: 6.551 s]
  Range (min … max):   39.460 s … 66.296 s    5 runs

Benchmark 4: torf --threads 12 ~/torrents/qbittorrent/tv/Show.S01.1080p.SRC.WEB-DL.DDP5.1.H.264-GRP
  Time (mean ± σ):     58.187 s ±  5.787 s    [User: 7.185 s, System: 6.511 s]
  Range (min … max):   50.125 s … 65.807 s    5 runs

Summary
  mkbrr create ~/torrents/qbittorrent/tv/Show.S01.1080p.SRC.WEB-DL.DDP5.1.H.264-GRP ran
    1.17 ± 0.26 times faster than torrenttools create --threads 12 ~/torrents/qbittorrent/tv/Show.S01.1080p.SRC.WEB-DL.DDP5.1.H.264-GRP
    1.42 ± 0.15 times faster than torf --threads 12 ~/torrents/qbittorrent/tv/Show.S01.1080p.SRC.WEB-DL.DDP5.1.H.264-GRP
    1.66 ± 0.65 times faster than mktorrent ~/torrents/qbittorrent/tv/Show.S01.1080p.SRC.WEB-DL.DDP5.1.H.264-GRP

hyperfine --warmup 1 --runs 5 \
  --prepare 'rm -f Show.S01.1080p.SRC.WEB-DL.DDP5.1.H.264-GRP.torrent' \
  'mkbrr create ~/Desktop/Show.S01.1080p.SRC.WEB-DL.DDP5.1.H.264-GRP' \
  'mktorrent ~/Desktop/Show.S01.1080p.SRC.WEB-DL.DDP5.1.H.264-GRP' \
  'torf --threads 10 ~/Desktop/Show.S01.1080p.SRC.WEB-DL.DDP5.1.H.264-GRP'

Benchmark 1: mkbrr create ~/Desktop/Show.S01.1080p.SRC.WEB-DL.DDP5.1.H.264-GRP
  Time (mean ± σ):      9.708 s ±  0.355 s    [User: 10.823 s, System: 4.297 s]
  Range (min … max):    9.479 s … 10.323 s    5 runs

Benchmark 2: mktorrent ~/Desktop/Show.S01.1080p.SRC.WEB-DL.DDP5.1.H.264-GRP
  Time (mean ± σ):     10.897 s ±  0.701 s    [User: 11.021 s, System: 3.038 s]
  Range (min … max):    9.950 s … 11.620 s    5 runs

Benchmark 3: torf --threads 10 ~/Desktop/Show.S01.1080p.SRC.WEB-DL.DDP5.1.H.264-GRP
  Time (mean ± σ):      9.779 s ±  0.749 s    [User: 10.776 s, System: 5.253 s]
  Range (min … max):    9.383 s … 11.112 s    5 runs

Summary
  mkbrr create ~/Desktop/Show.S01.1080p.SRC.WEB-DL.DDP5.1.H.264-GRP ran
    1.01 ± 0.09 times faster than torf --threads 10 ~/Desktop/Show.S01.1080p.SRC.WEB-DL.DDP5.1.H.264-GRP
    1.12 ± 0.08 times faster than mktorrent ~/Desktop/Show.S01.1080p.SRC.WEB-DL.DDP5.1.H.264-GRP

License

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

See LICENSE for the full license text.