File Operations

In addition to running code ampy you can also manipulate files on a MicroPython board's filesystem.  You can copy files from your computer to the board, read files from the board back to your computer, and even create and manage directories on the board.

Think of the filesystem on a MicroPython board like the filesystem on your computer.  Just like on your computer your board can have a complex hierarchy of directories with files and other subdirectories inside them.  MicroPython's filesystem is similar to Unix filesystems that separate parts of the path with forward slashes ('/') between parent directories.  For example a file /foo/bar.txt on a MicroPython board exists in a folder foo under the root of the board.

Copy Files to Board

The put command can copy files from your computer to a MicroPython board.  This is great for copying over Python source code and other files you create on your computer.

For example to copy a file called test.py from your computer to the root of a MicroPython board's filesystem under /test.py run the following command:

ampy --port /serial/port put test.py

Where /serial/port is the path or name of the serial port connected to the MicroPython board.  Make sure test.py is in the same directory as you're running the command too.  If the file isn't there then specify the full path to it on your computer.

You can also put the file on the board in a path other than the root. Just specify as another argument the full path and filename to use on the board.  For example to copy a test.py from your computer to a file /foo/bar.py on the board run (note the parent foo directory must already exist!):

ampy --port /serial/port put test.py /foo/bar.py
The put command will always overwrite files on the board without warning!

Copy Directories to Board

In addition to copying files the put command can also copy an entire directory and all of its child files and folders to the board.  This is perfect for copying a MicroPython module or other directory to the board.  For example if you have a folder called adafruit_driver that contains files and subfolder with driver code, you can copy it to your board with a command like:

ampy --port /serial/port put adafruit_driver

This command will copy the adafruit_driver folder (which should be in the same directory as the terminal you're running the command from) to the board's root.  If the folder already exists the contents will be copied over and replaced without warning!

You can also change the path that the folder is copied into, for example to copy adafruit_driver to the path /foo/adafruit_driver_2 on the board you can run:

ampy --port /serial/port put adafruit_driver /foo/adafruit_driver_2
The put command will always overwrite files on the board without warning!

Be sure you've updated ampy to the latest version as earlier versions did not support directory copying with put!

Read Files From Board

The get command can read and copy files from a MicroPython board to your computer.

For example to print the contents of /boot.py from a board run the following command:

ampy --port /serial/port get boot.py

This will print out the contents of boot.py from the board's root directory.

You can instead copy the contents of boot.py into a file on your computer by specifying the path to the file to save as a second argument.  For example to copy /boot.py from a board to a file board_boot.py on your computer you can run:

ampy --port /serial/port get boot.py board_boot.py
The get command will always overwrite files on the computer without warning!

Create Directories

You can create hierarchies of folders on the MicroPython board's filesystem with the mkdir command.

For example to create a /foo folder under the root of a board run the following command:

ampy --port /serial/port mkdir foo

You can create directories inside directories too, for example to create a folder bar inside the foo folder above you can run:

ampy --port /serial/port mkdir /foo/bar

Make sure the parent foo directory exists before trying to create the bar subdirectory inside of it!  The mkdir command won't create parent directories that don't exist.

List Directories

You can list the file and folder contents of a directory with the ls command.

If you don't specify any argument to the ls command then the contents of the MicroPython board's root will be listed.  However if you'd like to list the contents of a different directory just specify its path on the board as an argument.

For example to list the root contents of a board run:

ampy --port /serial/port ls

Or to list the contents of a subfolder foo run:

ampy --port /serial/port ls /foo

Remove Files & Directories

The rm command can remove a file or directory from a MicroPython board's filesystem.  To use the command just specify as an argument the path to the file or directory on the board to delete.  Note that directories must be empty before they can be deleted!

For example to delete a file test.py in the root of a board run the following commmand:

ampy --port /serial/port rm test.py

Or to delete a folder /foo/bar, assuming it's empty, run the following command:

ampy --port /serial/port rm /foo/bar

In addition ampy now has a rmdir command that will remove a directory and all of its child files and folders (even if they aren't empty).  For example to delete the folder /foo/bar on the board filesystem regardless of it containing child files and folders run the following command:

ampy --port /serial/port rmdir /foo/bar
The rm and rmdir commands will delete files and folders without warning or asking to confirm!

Be sure you've updated ampy to the latest version as earlier versions did not support the rmdir command.

This guide was first published on Aug 22, 2016. It was last updated on Nov 14, 2018. This page (File Operations) was last updated on Jan 26, 2017.