The torrent file

It is never the data itself. A description weighing a few tens of kilobytes stands in for something thousands of times larger, and the client holding it can verify every byte that arrives without trusting whoever sent it.

What a torrent file is, and what is inside it

A torrent file is a single file with the extension .torrent, written in a compact encoding called bencode that stores strings, integers, lists and dictionaries with no whitespace and no ambiguity. Open one in a text editor and you get a wall of characters with a few readable words in it, because the piece hashes are raw binary sitting in the middle of the text. It is not compressed and it is not an archive.

Every torrent file contains an info dictionary, the part that describes the data, plus a little housekeeping outside it. A hash of that dictionary is the info hash, the 20 byte identifier the swarm uses to recognize this exact set of data.

name

The suggested file name, or the folder name for a multi file torrent.

piece length

How large each piece is, conventionally a power of two, and the version 2 format makes that a requirement. Often a quarter or half a megabyte, and larger for very big sets.

pieces

Every piece hash laid end to end, 20 bytes each in the original format of 2001.

files

For a multi file torrent, the length and path of each file in order, with pieces running across the boundaries between them.

announce

The address of a tracker, with an announce list for any others.

private

A flag which, when set, tells clients not to use the distributed hash table or peer exchange here.

creation date and created by

Optional notes from whichever program built the file, sitting outside the info dictionary.

How a torrent file and a magnet link carry the same thing differently

A torrent file carries the description; a magnet link carries only the hash of it. A client given a torrent file already knows the file list, the piece count and every piece hash, so it can allocate disk space and start requesting pieces at once. A client given a magnet link knows only the info hash, so its first task is to fetch the description from the swarm, which is why a magnet link waits before it does anything visible.

The conversion runs both ways but not symmetrically. Going from a torrent file to a magnet link is arithmetic your machine does offline: hash the info dictionary, write the result as 40 hexadecimal characters, and the link is complete. Going the other way is a download, because the client must obtain the description from peers before it can write a .torrent out again. Most clients export one on request once the metadata has arrived, and qBittorrent, Transmission and Deluge all offer that on a running transfer.

How to check a torrent file before you open it

Every client shows you the entire contents of a torrent file before a single byte of data is fetched, and that check costs nothing. Adding a torrent and reading the dialog that appears is the check: it lists every file with its size, the total, the piece length, the piece count, the info hash and the trackers named inside. Cancelling leaves your disk untouched.

Three things in that dialog repay reading. The file list says what the torrent describes, which is not always what its name suggests. The total size says whether the description matches the kind of thing it claims to be. The info hash is the identity: two torrent files are the same torrent when their info hashes match, and the comments, the trackers and a magnet link's display name may all differ between them, because those sit outside the info dictionary. The name inside the info dictionary may not. How a transfer works follows what happens after that dialog is accepted, and whether the contents are safe to run is a separate question from whether the description is intact.

What opens a .torrent file on Windows, macOS and Linux

A torrent file is opened by a BitTorrent client and by nothing else in any useful sense. On Windows, macOS and Linux alike, installing a client registers the .torrent extension, so double clicking one hands it to that program and the add dialog appears. On macOS the association is set when the application is first launched, and a Mac with no client installed offers to search for one, because the system has nothing that understands the format.

• Install a client from the project that publishes it, then open the .torrent file with a double click.
• Drag the file into a running client window if the extension association went to the wrong program.
• Use the client's own open dialog, which accepts a path or a URL to a torrent file.
• Drop the file into a watch folder, if the client has one, and it is added automatically.
• Point a headless setup at the file through its web interface, which is how a machine with no screen is driven.

No online opener does anything meaningful, because opening a torrent file is not the hard part. Reading the description takes a fraction of a second; obtaining the data it describes takes a network and time. A browser can download a .torrent file, and some hand it straight to a client, but none turns one into the data.

Why nothing extracts a torrent file, and what an editor changes

Nothing extracts a torrent file because there is nothing inside it to extract. An extractor is a model borrowed from archive formats, where the container really does hold compressed copies. A torrent file holds names, lengths and hashes, so an extraction tool run over one produces an error, and a converter promising to turn a torrent into a video or an installer is describing something the format cannot do.

An editor is a real category. Clients and torrent creation tools let you change the parts outside the info dictionary: the tracker list, the comment, the created by string and the web seed addresses. Those edits are safe because the info hash does not move, so the edited file still joins the same swarm. Touch anything inside the info dictionary, including the name, the piece length or the file list, and you have created a different torrent with a different info hash, describing a swarm that may well have nobody in it. The swarm is defined by that hash and by nothing else in the file.