Writing Code Onto MicroPython Boards

Updated 08 February 2019

You have your shiny new MicroPython or Circuit Python board and you have Installed the Firmware and connected to REPL, but now you want to put your code onto the board. To do this we need to send the files over serial. Luckily Adafruit has made a tool for this that runs in python(This language has tools for everything!) We are going to have a look at using Ampy to copy your python files onto a MicroPython Board.

MicroPython and Circuit Python Boards

What we need

Python Files in MicroPython

MicroPython has a couple of files on it that you will need to know about so that you do not get unintended behaviours.  


This python script runs when the MicroPython board boots up and contains a lot of the setup for the board you are using. Be careful that you do not accidentally overwrite this file with another boot.py or you may get strange results.


This will be your main python program MicroPython will run this and you can put anything you like in here. If you copy another python file such as myScript.py onto the board it will not run it unless it is called from within main.py

Install Ampy

The first thing we are going to need to do is to install Adafruit Ampy, it is in the Python repositories so we can easily do this by opening a Terminal window and running:

pip install adafruit-ampy

Note: You may need to use sudo on Linux systems

Using Ampy

We can use ampy through the command line interface shown below. We will go through what the options are and then give a demonstration of how to use it when we get to the commands.


Information Options

The first options do not need any commands and will only return information about

--version Returns the Version of Ampy you are using.

			 ampy --version

--help Displays a list of all the commands available or show specific help for a command.

			ampy --help
			ampy -p <port> <command> --help

Connection Options

  -p         Tells ampy which port you want to connect to, you need to specify this option each time you run ampy.  

  -b         Sets the Baud rate (or speed) of the serial connection. If left undefined Ampy will assume 115200

  -d          Delay in seconds before entering RAW mode


Here is a list of the commands and options that can be used to interact and copy files to your MicroPython board. 


Description: List contents of a directory on the board.


                -l             long format

                -r             Recursive Show all files and directories                  


                ampy -p <port> ls <options>


Description: Upload a file or folder to the board. Specifying a second argument will change the name of the uploaded file or folder.


			ampy -p <port> get <localFileOrFolder> {NameOnBoard}


Description: Download the file specified from the board. Specifying a second argument will change the name of the downloaded file.


			ampy -p <port> get <FileToGet> {Local File}


Description: Make a new folder on the board


                --exists-okay     ignore this command if the folder is already there.


			ampy -p <port> mkdir <options> <directoryName>


Description: reset or reboot the board. Some of these options may only be available on all boards.


                --bootloader      Restart the board into the bootloader

                --hard                   Hard reboot and run init.py

                --repl                    Soft reboot and into the REPL this is the default option

                --safe                    Restart without running user code and make file system available over USB


			ampy -p <port> reset <Option>


Description: Remove a file or empty Folder from the board, it will not remove folders with files in them.


			ampy -p <port> rm <NameOfTarget>


Description: Delete a folder and all the files and folders within.


                --missing-okay                  Ignore this command if the folder does not exist


			ampy -p <port> rmdir <NameOfTarget>


Description: Run a script and display the output. This will not allow you to send inputs to your code.


                -n            run the script but do not wait for it to end to print the output. You should use this if your code will loop forever.


			ampy -p <port> run <option> <LocalFileName>

Copy Files to MicroPython


Now we know how to use Ampy we can copy some code over to our MicroPython Board. To do this we can open a terminal window and run the mode command to find the port.

Create a python file and name it main.py and fill it with the following code.

import machine # Generic library for MicroPython Hardware
print("Hello I am MicroPython") # print some Text.
print("I can do",machine.freq(),"things per second") # Get the Frequency of the CPU

Navigate to your where you saved your python file is using the command prompt.

Terminal Commands to navigate and upload file to Micropython

Now run the ampy command to copy the file over to the MicroPython board.

                ampy -p <port> put main.py

you should now see the output of the code we just put onto the MicroPython board.


Files Copied!

Now we have our script copied to the board and it will run every time the board is powered up. You can play around with adding other files and creating directories as well as running local files without copying them with the run command. If you have any cool ideas or projects you want to share based on this article join the discussion at the bottom of the page. 

If you want to learn more about MicroPython have a look at our tutorials and workshops.

Thanks for following this tutorial and all the best with your MicroPython Projects. 

Have a question? Ask the Author of this guide today!

Please enter minimum 20 characters

Your comment will be posted (automatically) on our Support Forum which is publicly accessible. Don't enter private information, such as your phone number.

Expect a quick reply during business hours, many of us check-in over the weekend as well.



Please continue if you would like to leave feedback for any of these topics:

  • Website features/issues
  • Content errors/improvements
  • Missing products/categories
  • Product assignments to categories
  • Search results relevance

For all other inquiries (orders status, stock levels, etc), please contact our support team for quick assistance.

Note: click continue and a draft email will be opened to edit. If you don't have an email client on your device, then send a message via the chat icon on the bottom left of our website.

Makers love reviews as much as you do, please follow this link to review the products you have purchased.