Magnet links
A magnet link is an address made out of a hash.
It identifies a set of data by its fingerprint rather than by its location, which is why it can be a line of text in a message instead of a file you keep, and why a client given one must ask the swarm for everything else. The string begins with magnet:? and carries named fields separated by ampersands, of which exactly one is mandatory.
What a magnet link is, and what it is not
A magnet link is a URI scheme rather than a BitTorrent invention, though BitTorrent is where almost everybody meets it. It names content by hash, so any program recognizing the hash can find the content by whatever means it has. A web address says where; a magnet link says which. Move the data to another machine and the web address breaks while the magnet link still resolves, because the identity travels with the bytes.
The mandatory field is xt, the exact topic, and in a BitTorrent link it holds the info hash: 40 hexadecimal characters in the original version of the format, or a 32 character base32 form of the same 20 bytes. Two magnet links with different display names and different tracker fields point at the same swarm whenever their xt values match. Everything else is a hint, and a link carrying nothing but xt is valid and still works, given time.
How to get a magnet link from a torrent file, and why the reverse is slower
Getting a magnet link out of a torrent file is instant, because the hash is computable from the file you already hold. Any client with the torrent loaded produces the link from a context menu, and qBittorrent, Transmission and Deluge all offer it. No network is involved: the client hashes the info dictionary it has and writes the result out as text.
The reverse cannot be done offline. The link carries the hash of the description, not the description, so the client must connect to the swarm, request the metadata from a peer that has it, verify that what arrives hashes to the value in the link, and only then write a .torrent out. A converter claiming to do that without a network is claiming to reverse a hash, which is what a hash is built to prevent.
How to check a magnet link before you add it
The check that matters is the one your own client performs, before any data is fetched. Paste the link, and the client resolves the metadata and shows the file list, the total size, the piece count and the info hash in the same dialog a torrent file would produce. Nothing is written to disk beyond the description. Reading the string by eye is quicker and needs no tool.
- Confirm the xt field is present and holds a full length hash, since a truncated one never resolves.
- Read the dn field, remembering it is a display name typed by whoever made the link and verified by nothing.
- Note whether tr fields are present, because a link with no trackers depends entirely on the distributed hash table.
- Treat any xl size field as a claim rather than a fact, since the real total arrives with the metadata.
What every field in the string means
| Field | Name | What it carries |
|---|---|---|
| xt | exact topic | The info hash, as urn:btih: followed by the hash. The only required field. |
| dn | display name | A suggested name shown while metadata is arriving. Cosmetic, and not verified. |
| tr | tracker | A tracker address to announce to, repeated once per tracker. |
| xl | exact length | The claimed total size in bytes. Optional and often absent. |
| ws | web seed | An ordinary web address that also serves the same data over HTTP. |
| x.pe | peer | A specific peer address to try at once, skipping the discovery step. |
The second version of the format, BEP 52, uses urn:btmh: instead of urn:btih:, carrying a multihash rather than a bare hash, and a hybrid torrent presents both so clients of either generation find what they understand. Unrecognized fields are ignored rather than treated as errors.
Why a magnet link takes a moment to start
A magnet link takes a moment because the client must fetch the description before it can ask for one piece. The sequence is fixed: find a peer holding this info hash, connect, discover it supports the metadata extension, request the description in blocks, verify the result hashes to the value in the link, then open the add dialog. That is usually tens of seconds rather than minutes, and longer with no tr fields, because the only route to a first peer is the distributed hash table.
The status line during this says something like metadata, and it is not a stall: the client simply does not yet know what it is downloading. How a transfer works picks up where the description has arrived. A media player pointed at the folder finds nothing, and even once pieces arrive they arrive out of order, so playing a partial file needs the client's sequential download option rather than a cleverer player.
Why a magnet link does nothing when you click it
A magnet link that does nothing has almost always failed at the handoff between browser and client, not inside the swarm. A browser cannot act on the magnet: scheme by itself: the operating system has to know which installed program claims it, and that registration happens when a client is installed or first launched.
- Install a client, if none is present, since the browser has nothing to hand the link to.
- Launch the client once by hand, which is when most of them register the magnet: scheme.
- Copy the string into the client's add link dialog, bypassing the browser association entirely.
- Check the browser's permission prompt, since many ask once and remember a refusal.
- Enable the distributed hash table in settings, if the link resolves nowhere at all.
A link that opens the client and then sits at metadata forever is a network failure instead. The usual cause is that the client cannot accept incoming connections, which most clients report as firewalled, and which is addressed by forwarding the listening port on the router. Firewalled means no incoming connection rather than no connection: the client still reaches out, but most of the swarm cannot reach it. A magnet link carrying a BitTorrent info hash also means nothing to a client that does not speak BitTorrent, and Napster in particular had nothing of the kind. Content addressed systems such as IPFS name data by hash in their own form.