Hardlink Mode

Hardlink mode is an opt-in cross-seeding strategy that creates a hardlinked copy of the matched files laid out exactly as the incoming torrent expects, then adds the torrent pointing at that hardlink tree. This can make cross-seed alignment simpler and faster, because qBittorrent can start seeding immediately without file rename alignment.

When to Use

• You want cross-seeds to have their own on-disk directory structure (per tracker / per instance / flat), while still sharing data blocks with the original download.
• You want to avoid qBittorrent rename-alignment and hash rechecks for layout differences.

Requirements

• Requires Local filesystem access on the target qBittorrent instance.
• Hardlink base directory must be on the same filesystem/volume as the instance's download paths (hardlinks can't cross filesystems).
• qui must be able to read the instance's content paths and write to the hardlink base directory.

Docker: Local Filesystem Access

Several qui features require access to the same filesystem paths that qBittorrent uses (orphan scan, hardlinks, reflinks, automations).

Mount the same paths qBittorrent uses - paths must match exactly:

volumes:
  - /config:/config
  - /data/torrents:/data/torrents  # Must match qBittorrent's path

After mounting, enable Local Filesystem Access on each instance in qui's Instance Settings.

Behavior

• Hardlink mode is a per-instance setting (not per request). Each qBittorrent instance can have its own hardlink configuration.
• If hardlink mode is enabled and a hardlink cannot be created (no local access, filesystem mismatch, invalid base dir, etc.), the cross-seed fails (no fallback to the default mode).
• Hardlinked torrents are still categorized using your existing cross-seed category rules (.cross suffix / "use indexer name as category"); the hardlink preset only affects on-disk folder layout.

Directory Layout

Configure in Cross-Seed → Hardlink Mode → (select instance):

• Hardlink base directory: path on the qui host where hardlink trees are created.
• Directory preset:
  • flat: base/TorrentName--shortHash/...
  • by-tracker: base/<tracker>/TorrentName--shortHash/...
  • by-instance: base/<instance>/TorrentName--shortHash/...

Isolation Folders

For by-tracker and by-instance presets, qui determines whether an isolation folder is needed based on the torrent's file structure:

• Torrents with a root folder (e.g., Movie/video.mkv, Movie/subs.srt) → files already have a common top-level directory, no isolation folder needed
• Rootless torrents (e.g., video.mkv, subs.srt at top level) → isolation folder added to prevent file conflicts

When an isolation folder is needed, it uses a human-readable format: <TorrentName--shortHash> (e.g., My.Movie.2024.1080p.BluRay--abcdef12).

For the flat preset, an isolation folder is always used to keep each torrent's files separated.

How to Enable

1. Enable "Local filesystem access" on the qBittorrent instance in Instance Settings.
2. In Cross-Seed → Hardlink Mode, expand the instance you want to configure.
3. Enable "Hardlink mode" for that instance.
4. Set "Hardlink base directory" to a path on the same filesystem as your downloads.
5. Choose a directory preset (flat, by-tracker, by-instance).

Pause Behavior

By default, hardlink-added torrents start seeding immediately (since skip_checking=true means they're at 100% instantly). If you want hardlink-added torrents to remain paused, enable the "Skip auto-resume" option for your cross-seed source (Completion, RSS, Webhook, etc.).

Notes

• Hardlinks share disk blocks with the original file but increase the link count. Deleting one link does not necessarily free space until all links are removed.
• Windows support: folder names are sanitized to remove characters Windows forbids. Torrent file paths themselves still need to be valid for your qBittorrent setup.
• Hardlink mode supports extra files when piece-boundary safe. If the incoming torrent contains extra files not present in the matched torrent (e.g., .nfo/.srt sidecars), hardlink mode will link the content files and trigger a recheck so qBittorrent downloads the extras. If extras share pieces with content (unsafe), the cross-seed is skipped.

Reflink Mode (Alternative)

Reflink mode creates copy-on-write clones of the matched files. Unlike hardlinks, reflinks allow qBittorrent to safely modify the cloned files (download missing pieces, repair corrupted data) without affecting the original seeded files.

Key advantage: Reflink mode bypasses piece-boundary safety checks. This means you can cross-seed torrents with extra/missing files even when those files share pieces with existing content—the clones can be safely modified.

When to Use Reflink Mode

• You want to cross-seed torrents that hardlink mode would skip due to "extra files share pieces with content"
• Your filesystem supports copy-on-write clones (BTRFS, XFS on Linux; APFS on macOS)
• You prefer the safety of copy-on-write over hardlinks

Reflink Requirements

• Local filesystem access must be enabled on the target qBittorrent instance.
• The base directory must be on the same filesystem/volume as the instance's download paths.
• The base directory must be a real filesystem mount, not a pooled/virtual mount (common examples: mergerfs, other FUSE mounts, overlayfs).
• The filesystem must support reflinks:
  • Linux: BTRFS, XFS (with reflink=1), and similar CoW filesystems
  • macOS: APFS
  • Windows/FreeBSD: Not currently supported

tip

On Linux, check the filesystem type with df -T /path (you want xfs/btrfs, not fuseblk/fuse.mergerfs/overlayfs).

Behavior Differences

Aspect	Hardlink Mode	Reflink Mode
Piece-boundary check	Skips if unsafe	Never skips (safe to modify clones)
Recheck	Only when extras exist	Only when extras exist
Disk usage	Zero (shared blocks)	Starts near-zero; grows as modified

Disk Usage Implications

Reflinks use copy-on-write semantics:

• Initially, cloned files share disk blocks with originals (near-zero additional space)
• When qBittorrent writes to a clone (downloads extras, repairs pieces), only modified blocks are copied
• In worst case (entire file rewritten), disk usage approaches full file size

How to Enable Reflink Mode

1. Enable "Local filesystem access" on the qBittorrent instance in Instance Settings.
2. In Cross-Seed > Hardlink / Reflink Mode, expand the instance you want to configure.
3. Enable "Reflink mode" for that instance.
4. Set "Base directory" to a path on the same filesystem as your downloads.
5. Choose a directory preset (flat, by-tracker, by-instance).

note

Hardlink and reflink modes are mutually exclusive—only one can be enabled per instance.