> ## Documentation Index
> Fetch the complete documentation index at: https://mkbrr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Creating torrents

> Learn how to create .torrent files from local files or directories using the mkbrr create command

The `mkbrr create` command is used to generate new `.torrent` files from local files or directories.

```bash theme={null}
mkbrr create [path] [flags]
```

This command supports creating torrents for single files or entire directories. It also integrates with [Presets](/features/presets) and [Batch Mode](/features/batch-mode) for more advanced workflows.

<CardGroup>
  <Card title="Arguments" icon="list-check" href="#arguments">
    Required and optional command arguments
  </Card>

  <Card title="Flags" icon="flag" href="#flags">
    Available command flags and options
  </Card>

  <Card title="Smart Defaults" icon="wand-magic-sparkles" href="#smart-defaults">
    Automatic optimizations and settings
  </Card>

  <Card title="Examples" icon="code" href="#examples">
    Common usage examples
  </Card>
</CardGroup>

## Smart Defaults

mkbrr automatically optimizes several settings for you:

<CardGroup cols={2}>
  <Card title="Piece Size" icon="puzzle-piece">
    Automatically calculated based on content size for optimal performance and tracker compatibility
  </Card>

  <Card title="File Name" icon="file">
    Generated from tracker domain and content name if not specified (e.g., `tracker-domain_content-name.torrent`)
  </Card>

  <Card title="Private Flag" icon="lock">
    Enabled by default for private tracker compatibility. Use `--private=false` for public trackers
  </Card>

  <Card title="Tracker Rules" icon="shield" href="/features/tracker-rules">
    Automatically enforces piece size limits and other requirements based on tracker URL. See [Tracker Rules](/features/tracker-rules) for details.
  </Card>
</CardGroup>

<Note>
  When you provide a tracker URL via the `-t` flag or presets, mkbrr automatically detects and applies the appropriate tracker-specific rules to ensure your torrents are compliant.
</Note>

## Arguments

* `[path]`: (Required unless using `-b`) The path to the source file or directory you want to create a torrent from.

## Flags

### Input & Output

<ParamField query="--tracker, -t" type="string[]">
  Tracker URL. Can be specified multiple times to add several trackers. Optional.
</ParamField>

<ParamField query="--name" type="string">
  Set torrent name (default: source filename).
</ParamField>

<ParamField query="--output, -o" type="string">
  Optional. Set output path (default: `<n>.torrent` or `<tracker-prefix>_<n>.torrent`).
</ParamField>

<ParamField query="--output-dir" type="string">
  Output directory for created torrent.
</ParamField>

<ParamField query="--skip-prefix" type="boolean" default={false}>
  Don't add tracker domain prefix to output filename.
</ParamField>

### Advanced Input (Batch & Presets)

<ParamField query="--batch, -b" type="string">
  Batch config file (YAML). Cannot be used with a path argument.

  <Info>
    For creating multiple torrents in one go. See the [Batch Mode](/features/batch-mode) documentation for details.
  </Info>
</ParamField>

<ParamField query="--preset, -P" type="string">
  Use preset from config.

  <Info>
    For reusing common settings across torrents. See the [Presets](/features/presets) documentation for details.
  </Info>
</ParamField>

<ParamField query="--preset-file" type="string">
  Preset config file (default `~/.config/mkbrr/presets.yaml`).

  <Info>
    Set custom path to presets.yaml. See the [Presets](/features/presets) documentation for details.
  </Info>
</ParamField>

### Content Selection

<ParamField query="--exclude" type="array">
  Exclude files matching these patterns (e.g., `"*.nfo,*.jpg"` or `--exclude "*.nfo" --exclude "*.jpg"`).

  <Tip>
    Use this to filter out unwanted files like NFOs, samples, or extras that shouldn't be in the torrent. See the [filtering guide](/features/filtering) for detailed pattern rules and examples.
  </Tip>
</ParamField>

<ParamField query="--include" type="array">
  Include only files matching these patterns (e.g., `"*.mkv,*.mp4"` or `--include "*.mkv" --include "*.mp4"`).

  <Tip>
    Using include patterns activates whitelist mode. See the [filtering guide](/features/filtering) for detailed pattern rules and examples.
  </Tip>
</ParamField>

### Torrent Internals

<ParamField query="--private, -p" type="boolean" default={true}>
  Make torrent private.

  <Note>
    Private flag is enabled by default for tracker compliance. Only disable if you're creating a public torrent.
  </Note>
</ParamField>

<ParamField query="--piece-length, -l" type="number">
  Set piece length to 2^n bytes (16-27, automatic if not specified).
</ParamField>

<Tip>
  Let mkbrr automatically calculate the piece size unless you have specific requirements. The automatic calculation optimizes for both performance and compatibility.
</Tip>

<ParamField query="--max-piece-length, -m" type="number">
  Limit maximum automatically calculated piece length to 2^n bytes (14-27).
</ParamField>

<ParamField query="--target-piece-count" type="number">
  Target approximate number of pieces. Calculates optimal piece length automatically.
  Mutually exclusive with `--piece-length`.
</ParamField>

<ParamField query="--entropy, -e" type="boolean" default={false}>
  Randomize the torrent's info hash by adding or updating a unique, random `entropy` key in the info dictionary before hashing.

  <Info>
    Cross-seeding is the practice of seeding the same content on multiple trackers. Using the entropy flag helps avoid conflicts between trackers.
  </Info>
</ParamField>

### Seeding & Metadata

<ParamField query="--web-seed, -w" type="array">
  Specify web seed URLs. Can be used multiple times.

  <Info>
    Web seeds provide an HTTP fallback source for the torrent content, improving availability.
  </Info>
</ParamField>

<ParamField query="--source, -s" type="string">
  Specify the source string.

  <Info>
    Some trackers require or recommend specific source tags. Check your tracker's rules.
  </Info>
</ParamField>

<ParamField query="--comment, -c" type="string">
  Specify a comment.
</ParamField>

<ParamField query="--no-date, -d" type="boolean" default={false}>
  Omit the creation date from the torrent metadata.
</ParamField>

<ParamField query="--no-creator" type="boolean" default={false}>
  Omit the creator string from the torrent metadata.
</ParamField>

### Season Pack Detection

<ParamField query="--fail-on-season-warning" type="boolean" default={false}>
  Exit with error if season pack completeness check detects missing episodes.
</ParamField>

### Execution & Output Control

<ParamField query="--workers" type="number">
  Manually specify the number of concurrent goroutines used for hashing.

  <Tip>
    Experimenting with different worker values *might* yield better performance than the default automatic setting.
  </Tip>
</ParamField>

<ParamField query="--verbose, -v" type="boolean" default={false}>
  Be verbose.
</ParamField>

<ParamField query="--quiet, -q" type="boolean" default={false}>
  Enable quiet mode, printing only the final torrent file path upon success. Useful for scripts.
</ParamField>

<ParamField query="--info-only, -i" type="boolean" default={false}>
  Display only torrent info without progress (implies verbose).
</ParamField>

## Handling Symbolic Links

When `mkbrr create` encounters symbolic links (symlinks) within the source path:

* **Links are followed:** `mkbrr` reads the content of the file or directory the link points to (the target).
* **Target content is hashed:** The torrent pieces will contain the hash data of the *target* file's content.
* **Link path is stored:** The file path recorded inside the `.torrent` file's metadata will be the path of the *symbolic link itself*, relative to the source path, not the path of the target.

This means the created torrent represents the file structure as it appears with the links, but the data integrity check (`mkbrr check`) will verify against the actual content pointed to by those links at the time of creation.

<Warning>
  Important: When checking a torrent created with symlinks using `mkbrr check`, the check verifies against the *original target content* that was hashed during creation, not necessarily what the link points to currently if the target file has changed or been moved.
</Warning>

## Examples

<Tabs>
  <Tab title="Basic Usage">
    Create a private torrent for a single file:

    ```bash theme={null}
    mkbrr create /path/to/movie.mkv -t https://private-tracker.com/announce -s "MyTracker"
    ```

    Create a public torrent for a directory:

    ```bash theme={null}
    mkbrr create /path/to/album-folder -t udp://public-tracker.org:6969/announce --private=false -c "Awesome Album"
    ```
  </Tab>

  <Tab title="Advanced Features">
    Create using a preset:

    ```bash theme={null}
    mkbrr create /path/to/content -P mypreset
    ```

    Create with specific piece size and web seeds:

    ```bash theme={null}
    mkbrr create /path/to/large-file.iso -t https://tracker.net/a -l 24 -w http://seed.example.com/large-file.iso
    ```

    Create with entropy for cross-seeding:

    ```bash theme={null}
    mkbrr create /path/to/content -t https://another-tracker.com/announce -e
    ```
  </Tab>

  <Tab title="File Filtering">
    Create excluding certain files:

    ```bash theme={null}
    mkbrr create /path/to/project/ -t https://tracker.net/a --exclude ".*,*.tmp,node_modules"
    ```

    Create including only video files:

    ```bash theme={null}
    mkbrr create /path/to/mixed-folder/ -t https://tracker.net/a --include "*.mkv,*.mp4,*.avi"
    ```
  </Tab>
</Tabs>