Your submission was sent successfully! Close

You have successfully unsubscribed! Close

Thank you for signing up for our newsletter!
In these regular emails you will find the latest updates about Ubuntu and upcoming events where you can meet our team.Close

Magic Wormhole – Send files with ease

This article is more than 4 years old.

Sharing is caring.

Alexander the Great

File transfer is the bread and butter of information exchange in the digital world. Documents, photos, videos, we share them with our colleagues and friends. The only problem is, the Internet is a global village with many languages – and we’re talking about software, not humans.

If you want to share a file with someone, typically, both you and the recipient need to use the same tools to do this successfully. Email works well for most people, but usually, there are arbitrary limits of the attachment size. Online sharing services that create download links are another useful possibility, and these do address most of the limitations of the multi-software mishmash that exists out there. For Linux users, there’s a third possibility – Magic Wormhole.

How does it work?

Magic. Well almost. User A simply “sends” the file they want. Before the content is actually sent, a short, simple-to-remember (or rather simple-to-repeat) password phrase is generated. User A then shares this phrase with whoever needs to receive the file on the other end. User B needs to type down this password when prompted by the Magic Wormhole tool. Once this step is complete, the file will be transferred between the two users, and there will be much rejoicing.

You can test for yourself. First, install Magic Wormhole.

snap install wormhole

Wormhole has a command-line interface. On system A, send a file – or even an entire directory if you like. The application will zip it up, and the directory contents will be unpacked automatically at the other end. Something like:

wormhole send "Hans Gruber quotes.ogg"
Sending 12.9 MB file named 'Hans Gruber quotes.ogg'
Wormhole code is: 9-virginia-ratchet
On the other computer, please run:

wormhole receive 9-virginia-ratchet

As you can see, the tool will let you know the password that you need to supply to the other party. On their system, the intended recipient can then type:

wormhole receive 9-virginia-ratchet

Both systems need to be online when this happens. If the source is not available, the transfer cannot run. If you’re testing this on your own, you can watch the file progress in the two terminal windows in parallel.

And that’s it.

There’s no such thing as magic!

Of course, under the hood, a lot of interesting things happen. The developer of the tool gave a PyCon 2016 presentation on his work, and the official documentation includes additional details on how Magic Wormhole functions.

In essence, there are three main components to the program. The interesting piece is the so-called Rendezvous Server (a WebSocket relay), which acts as a negotiator between the two endpoints – hence the name, wormhole. When the sender initiates the transfer, it will generate a cryptographic key pair (will be used to encrypt data during the transfer), contact the Rendezvous Server and supply the session key, as well as the sender IP address and port number for the connection. When the recipient contacts the server (with the correct password provided), it will send its half of the information over (including the correct session key) so that the two endpoints can be hooked together.

The transfer will then run – directly between the two systems if they can reach other directly. However, if the IP addresses or ports are not accessible (due to firewall or NAT), then the exchange of data will run through the relay. This also explains why both systems need to be running wormhole at the same time, because the data is not sent in advance and buffered, it is transferred in real-time once both sides negotiate their ends of the connection.

So if you’re wondering, yes, there might be network throughput limitations, especially if there are many transfers running simultaneously over the relay. The Rendezvous Server address is hard-coded into wormhole, but you can setup your own infrastructure if you want. The security model is relatively robust against eavesdropping, but like any sharing service, you do need to trust the infrastructure over which you’re sending information – you can always encrypt the data yourself.

Perhaps this is no magic, but it’s a pretty neat trick.


If you’re a technically savvy person, i.e. you can comfortably use the command line to manipulate files, then Wormhole Magic is a nice, flexible tool that can help you share content with other people in a rather secure manner. Should you have any feedback on comments on this topic, please join our forum, and let us know what you think.

No laws of physics or time-space continuum dimensions were harmed in the writing of this article.

Photo by Kamesh Vedula on Unsplash.

Ubuntu desktop

Learn how the Ubuntu desktop operating system powers millions of PCs and laptops around the world.

Newsletter signup

Get the latest Ubuntu news and updates in your inbox.

By submitting this form, I confirm that I have read and agree to Canonical's Privacy Policy.

Related posts

Managing software in complex network environments: the Snap Store Proxy

As enterprises grapple with the evolving landscape of security threats, the need to safeguard internal networks from the broader internet is increasingly...

We wish you RISC-V holidays!

There are three types of computer users: the end user, the system administrator, and the involuntary system administrator. As it happens, everyone has found... reloaded: check out the new look and feel

We’re happy to announce that has a fresh, new look! Time for an update After keeping the same user interface and style for several years, we...