ampy: a simple serial file and script tool for MicroPython boards

A file mover and script runner, not a terminal emulator

ampy is described in the README as a MicroPython tool, a utility to interact with a CircuitPython or MicroPython board over a serial connection. The intended shape of use is narrow and worth understanding before you install it. You can send files from your computer to the board's file system, download files from a board to your computer, and send a Python script to a board to be executed. That is the whole feature story, and the README is explicit that this is by design: ampy is meant to be simple and does not support advanced interaction like a shell or terminal to send input to a board. The tool ships as the PyPI package adafruit-ampy, and its command surface covers get, ls, mkdir, mv, put, rm, rmdir, run and reset.

Every invocation needs a port, and the raw mode delay is the usual failure point

The help output in the README shows the global options that shape a connection. The serial port is marked as required and is given with -p or --port, the baud rate with -b or --baud defaults to 115200, and -d or --delay sets a delay in seconds before entering RAW MODE, defaulting to 0. That delay is not a cosmetic option. The README's example .ampy file includes a comment about a fix for macOS users hitting a Could not enter raw repl error, and suggests trying 2.0 and lower from there. In practice the serial protocol ampy speaks requires the host to switch the port into raw mode, and on some systems the board needs a moment before it will talk. Serial port names are also platform specific, with the README using /dev/tty.SLAB_USBtoUART on macOS and a COM4 style name on Windows.

Installing from PyPI and installing from source

The README covers both paths. From the Python package index, on macOS or Linux with Python 3 the command is the following, and on Windows the same package name works with pip.

    pip3 install --user adafruit-ampy

Once installed, the README asks you to verify the tool by printing its help output, and to see the usage information.

    ampy --help

If you would rather work from the GitHub source, the README points at the standard setup.py install route, or develop mode.

    python3 setup.py install

The repository layout supports that path: a setup.py, a setup.cfg, a requirements.txt and an ampy package directory alongside tests. The requirements file is short, listing click, pyserial and python-dotenv, so the runtime surface is three dependencies, one for the command line interface, one for the serial port and one for loading environment variables.

Putting files on the board with ls, put and run

Usage is a matter of pointing the tool at a connected board. The README's first example lists the root directory of the board over a serial port on macOS.

    ampy --port /dev/tty.SLAB_USBtoUART ls

You should see the files in the board's root directory printed to the terminal, and you need to change the port value to whatever your own board enumerates as. Each subcommand carries its own help text, and the README notes the awkward part of that: to see the help for ls you must already have a board connected and a serial port specified.

    ampy --port /dev/tty.SLAB_USBtoUART ls --help

That ordering constraint is a small but real ergonomic cost, since the tool cannot describe itself offline. For scripted use, the same commands work with put to push a file and run to execute a script and print its output, which is how ampy is typically used in a build or deployment step.

AMPY_PORT, AMPY_BAUD and AMPY_DELAY, plus a .ampy file

Typing a port on every command gets old, so the README documents two conveniences. First, an AMPY_PORT environment variable is used when the port parameter is not given, and AMPY_BAUD and AMPY_DELAY do the same for baud rate and the delay before raw mode. On Linux or macOS you export the variable and then call ampy without a port flag.

    export AMPY_PORT=/dev/tty.SLAB_USBtoUART
    ampy ls

On Windows the README suggests the SET command, and marks that route as untested.

    set AMPY_PORT=COM4
    ampy ls

Second, you can put these settings in a file named .ampy so they load automatically every time you run ampy, and the README shows the exact format.

# Example .ampy file
# Please fill in your own port, baud rate, and delay
AMPY_PORT=/dev/cu.wchusbserial1410
AMPY_BAUD=115200
# Fix for macOS users' "Could not enter raw repl"; try 2.0 and lower from there:
AMPY_DELAY=0.5

The file can sit in your working directory, in one of its parents, or in your home directory, so a checked-in .ampy at the root of a project can hold the port for everyone on the team.

Where rshell and mpfshell are the better tool

The README itself points to alternatives, and the distinction is clean rather than a matter of taste. ampy gives you a set of one-shot commands: transfer a file, list a directory, run a script, reset the board. rshell and mpfshell are the tools to look at when you need an interactive shell or terminal against the board, and ampy explicitly declines to cover that ground. If your workflow is copying a script onto a board and rebooting it, ampy covers it cleanly and its simplicity is the advantage. If your workflow is exploring the filesystem interactively, typing into a REPL, or streaming input to a running program, ampy cannot do it and you should use one of the two tools the README names instead.

MIT licensed, but the release trail is old

The project is MIT licensed, with the permission notice carried in the setup.py header, so commercial and closed source use is fine as long as the notice is kept. The versioning picture is where caution is needed. The GitHub release list stops at 1.0.7 in October 2018, while setup.py declares version 1.2.0, so the two version signals do not agree and it is unclear from the README which one the package index reflects. The repository is not archived and the last push was on 2026-04-16, so there is recent commit activity even though the tagged releases are old. The repository also holds a PLAN.md and a .travis.yml file, pointing at a project that dates from an era of Travis-based continuous integration and manual setup.py installs.

Editorial conclusion

ampy suits scripts, CI jobs and quick manual transfers where a MicroPython board needs a file pushed to it or a script run without opening an interactive session. It does not suit anyone who needs a REPL prompt, shell access or streaming input, since the README states that advanced interaction is out of scope and points to rshell or mpfshell instead. Before adopting it, check that the serial port you pass matches the board, confirm the raw mode entry works on your host, and read the .ampy file format, since AMPY_PORT, AMPY_BAUD and AMPY_DELAY are the three settings that decide whether a connection succeeds.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. scientifichackers/ampy on GitHub