Hybrid torrent compatibility: what works across v1 and v2

A hybrid torrent lets v1-only clients and clients supporting BitTorrent v2 share the same files. It contains both formats’ metadata and hashes. An older client uses the v1 side; a client supporting both formats can participate in both swarms using the same local files. A v2-only torrent does not offer that backward compatibility. BEP 52 specifies this interoperability.

For a Linux image, open dataset or other files you have the right to distribute, hybrid is the format to consider when your audience uses a mixture of older and newer clients. But the torrent format and the magnet link used to open it are separate compatibility checks.

What each client can use

Here, “v1 + v2 client” means a client implementing both formats, including hybrid support—not merely an application that recognizes magnet links.

Torrent format	v1-only client	v1 + v2 client
v1-only	Uses v1	Uses v1
v2-only	Cannot use the torrent	Uses v2
Hybrid	Uses the v1 side	Can use both sides

The hybrid behavior is documented in libtorrent’s v2 upgrade guide. Actual support depends on the client and build. For example, Transmission introduced support for using v2 and hybrid torrents in 4.0.0; libtorrent introduced v2 support in 2.0. These are support milestones, not recommendations to install those old releases. Transmission release notes distinguish downloading support from torrent-creation support, so do not assume the two arrived together.

One payload, two torrent identities

A hybrid has two info-hashes: a v1 SHA-1 hash and a v2 SHA-256 hash. They identify the torrent metadata, not simply the filename or the raw contents of one downloaded file.

Those identities form two swarms, even though they serve the same payload. A client supporting both formats can join both and download into the same storage. In libtorrent, hybrid torrents announce to trackers once per info-hash, with tracker results reported separately for v1 and v2. libtorrent’s protocol explanation and upgrade documentation describe this arrangement.

That does not make a v1-only peer speak v2. Nor does it merge arbitrary torrents that happen to contain identical files. The bridge depends on valid hybrid metadata: BEP 52 requires matching filenames, file order and piece alignment, plus verification against both hash formats. If the two descriptions are inconsistent, an implementation may abort or use only one side. BEP 52’s hybrid requirements define these checks.

Also, recreating an existing v1 torrent as a hybrid is not a way to preserve its old swarm automatically. Adding v2 information changes the hashed info dictionary, so the resulting hybrid has a new v1 identity. Keep distributing the original torrent if retaining that original swarm matters. This follows from BEP 3’s definition of the v1 info-hash and BEP 52’s hybrid requirements.

A hybrid magnet should carry both hashes

Magnet links identify the two formats differently:

• xt=urn:btih: carries the v1 info-hash.
• xt=urn:btmh: carries the tagged v2 info-hash.

A backward-compatible hybrid magnet can include both xt parameters in the same URI. The v2 value uses hexadecimal multihash encoding: 1220 followed by the 64 hexadecimal characters of the full SHA-256 info-hash. BEP 9 documents the magnet prefixes, and libtorrent explains the dual-hash form.

A magnet containing only btmh does not give a v1-only client the v1 identifier it needs—even if the underlying torrent is hybrid. Conversely, a btih entry alone does not prove a torrent is hybrid; ordinary v1 torrents use it too.

For publishers, export the magnet from the actual hybrid torrent and preserve both hashes. Do not combine hashes from independently created v1 and v2 torrents. For readers whose older client cannot open the supplied magnet, ask the legitimate publisher for the hybrid .torrent file or a magnet including its v1 hash.

A magnet still needs peers that can supply metadata. A .torrent file avoids that initial metadata-retrieval step, but it does not create seeders or guarantee a completed download. See how magnet links retrieve metadata.

Why older clients may show padding files

BitTorrent v2 aligns each non-empty file to a piece boundary. A multi-file hybrid uses synthetic padding files on its v1 side where needed to maintain matching alignment. BEP 52 describes the alignment requirement.

Padding-aware clients need not write those files to disk and should avoid requesting their zero-filled contents. Older clients unaware of the extension may treat them as ordinary files. BEP 47 recommends placing them under .pad; files marked as padding are a compatibility artifact, not additional payload documents. The directory name alone does not establish that a file is padding. BEP 47 explains padding-file behavior.

When a hybrid will not start

Check these in order:

1. Confirm the format. “v2” and “hybrid” are not interchangeable. Check the publisher’s description and the client’s torrent details where available.
2. Check the magnet. For an older client, look for a btih entry. If it is missing, obtain the publisher’s hybrid .torrent or dual-hash magnet rather than inventing a hash.
3. Check the exact client build. Consult its documentation for v2 and hybrid support; a product name alone is not enough.
4. Separate rejection from waiting. An unsupported format or invalid metadata is a compatibility problem. If the client accepts the torrent but waits for metadata or available pieces, start by checking peer availability and connectivity rather than assuming the format is unsupported.

Hybrid provides a path between protocol generations. It does not promise more seeders or faster downloads: it lets compatible clients use whichever side has reachable peers and useful pieces.