Skip to content
Get packs

Guide · Open source

How to use magic-wormhole: send files between computers

Updated · written with AI from the project's own documentation and checked against our catalogue data

Magic Wormhole is an open-source library and command-line tool named wormhole that moves files, directories or short pieces of text from one computer to another. This guide explains how the wormhole code works, how to install the tool with pip, and how to send and receive something. By the end you will be able to run a one-off transfer from a terminal.

Magic Wormholemagic-wormhole/magic-wormhole · ★ 23.1k · MIT

Quick start

  1. 1Check your Python version. Confirm you have Python 3.10 or higher installed, since that is the stated requirement.
  2. 2Install the tool. Run pip install magic-wormhole to install the wormhole command from PyPI.
  3. 3Start the send. On the sending computer, run wormhole send with the file or folder you want to transfer.
  4. 4Share the code. Read the displayed code to the receiver or pass it along by another channel.
  5. 5Receive the transfer. On the receiving computer, run wormhole receive and type the code, using Tab to complete words.
  6. 6Finish. Once the transfer completes, the code is spent; start a new send for any further transfer.

What Magic Wormhole does

Magic Wormhole gets arbitrary-sized files and directories, or short pieces of text, from one computer to another. The two ends are matched using a wormhole code. In general, the sending machine generates and displays the code, and you type that code on the receiving machine.

The codes are short and human-pronounceable, built from a phonetically distinct wordlist. The receiving side offers tab-completion on the codewords, so usually only a few characters need typing. Codes are single-use and do not need to be memorized.

Install magic-wormhole with pip

The source describes Python 3.10 or higher as the requirement, and the library is tested against versions up to 3.12. Install it from PyPI with pip.

Magic Wormhole packages are also included in many operating systems. To install without an OS package, the README points to the Installation docs on the project's documentation site.

pip install magic-wormhole

Send a file or folder

On the sending computer, run wormhole send with the file or directory you want to transfer. The sending machine displays a code. Keep that code and give it to the person receiving the transfer, for example by reading it aloud or sending it through another channel.

The source states that files and directories of any size can be sent, and that the code is what connects the two endpoints.

  • Run the send command on the sending computer with the file or folder.
  • Note the code the sender displays.

Receive a file on the other computer

On the receiving computer, run wormhole receive and type the code shown by the sender. Start typing the first words and press Tab to complete them, since the wordlist supports tab-completion.

Because each code is single-use, a new transfer needs a new code.

  • Run wormhole receive on the receiving computer.
  • Type the code, using Tab to complete the codewords.
wormhole receive

Send short text

Magic Wormhole can also move short pieces of text, not only files. The source confirms this capability but the README does not list the exact flags, so check the full documentation for the options.

Use the library in scripts

Magic Wormhole also ships as a library. Developers who want to script transfers can use it from Python code instead of the command line. The README does not include code examples, so refer to the documentation for the API.

What people use it for

  • Sending a file to a colleague who has no shared drive or account set up.
  • Moving a folder between two of your own machines from a terminal.
  • Sharing a short piece of text with someone nearby who can read a code.
  • Scripting one-off transfers in a Python program using the provided library.

Frequently asked questions

Is magic-wormhole free?

Magic Wormhole is released under the MIT license, according to the README, and the LICENSE file has the details. The source does not mention any paid tier.

What do I need to run magic-wormhole?

The source states Python 3.10 or higher is required, and the library is tested up to Python 3.12. You install it with pip install magic-wormhole.

How do I install magic-wormhole?

Run pip install magic-wormhole to install it from PyPI. The README also notes that many operating systems ship packages, and points to the Installation docs for non-OS installs.

Is there a graphical version of magic-wormhole?

The README describes only a command-line tool and a library. If you need a graphical app, the source does not offer one, so consider a comparable project such as LocalSend.

Can I send one file to several people?

No. Wormhole codes are single-use, so each recipient transfer needs its own code. Tools built for many recipients may suit you better.

How does magic-wormhole compare to croc or Syncthing?

The source lists croc, LocalSend and Syncthing as comparable projects but does not compare features. Magic Wormhole is a direct one-off transfer tool, not hosted storage or continuous file sync.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Magic Wormhole suits people who are comfortable in a terminal and want a quick, one-off transfer without creating an account. It is a poor fit if you need a graphical app, need to send to many recipients at once, or want hosted long-term storage; in those cases look at comparable projects like LocalSend or Syncthing.

Install options & downloads