Moving Files Between Machines Without the Usual Hassle

You've got a file on your laptop and you need it on the other machine across the room. So you reach for a USB stick, or spin up a quick SCP command, or email it to yourself, or dump it into some cloud folder and wait for a sync. None of it's hard, exactly, but none of it's pleasant either. Magic Wormhole is a small command-line tool (and Python library) that takes a different approach: you generate a short code on one machine, type it into the other, and the file lands where you want it.

What It Does

Magic Wormhole lets you get arbitrary-sized files and directories (or short pieces of text) from one computer to another. The two endpoints are identified by identical "wormhole codes." In practice, the sending machine generates and displays the code, and you type that code into the receiving machine to pair them up.

The codes are short and human-pronounceable, built from a phonetically-distinct wordlist. The receiving side offers tab-completion on the codewords, so usually you only need to type a few characters. The codes are single-use and don't need to be memorized. Under the hood, the project relies on two servers whose source lives in separate repositories: a mailbox server and a transit relay. It's released under the MIT license and compatible with Python 3.10 and higher (tested up to 3.12).

Why It's Cool

• The code is the whole interface. There's no account setup, no shared folder, no pre-existing trust relationship between the two machines. You generate a code, you say it out loud or read it off a screen, and that's the handshake. The single-use design means you don't have to worry about a code lingering after the transfer is done.

• Human-pronounceable, not just human-readable. A lot of tools generate ugly strings you'd never want to dictate over a phone call. This one uses a phonetically-distinct wordlist specifically so the codes work when spoken. That's a small detail, but it's the kind of thing that reveals the tool was designed around real usage, not just the happy path.

• Tab-completion makes typing nearly free. Because the receiving side completes the codewords as you type, you usually only punch in a few characters. It's a nice bit of polish that keeps the friction low without sacrificing the security model.

• It handles directories and big files. This isn't just a text-paste utility. Arbitrary-sized files and whole directories are in scope, which covers most of the "I just need to move this over there" situations you actually run into.

• The servers are open and separate. The mailbox server and transit relay live in their own repositories rather than being baked into the client. If you care about where your data flows, you can go read that code.

How to Try It

Magic Wormhole is packaged for many operating systems, so there's a decent chance your package manager already has it. The Repology badge in the README is the quickest way to check your platform.

If you'd rather install it without an OS package, follow the installation docs at the project's ReadTheDocs site. The basic flow once you have it:

1. On the sending machine, run wormhole send with the file or directory you want to move.
2. Note the code it displays.
3. On the receiving machine, run wormhole receive and enter that code (tab-completion will help).
4. The transfer happens between the two machines.

For complete documentation, see https://magic-wormhole.readthedocs.io or the docs/ subdirectory in the repo. You can grab the source and read more at github.com/magic-wormhole/magic-wormhole. If you want the background, there's a PyCon 2016 talk linked from the README with slides and video.

Final Thoughts

Magic Wormhole is best for people who move files between machines often enough to be annoyed by the alternatives, but don't want to set up anything permanent to do it. The short spoken code is a genuinely thoughtful interface choice, and the single-use design keeps things simple. It's a focused tool that does one thing well, and if that thing matches a task you do regularly, it'll earn a spot in your terminal history. Worth a look, especially since it's probably already in your package manager.