Learn electronics, coding, and projects — step by step.

Micropython Basics: File Management

Table of Contents

Once you’ve explored the REPL and tested small snippets of code interactively, the next step is learning how to save and manage scripts on your MicroPython board. This allows your programs to run automatically, even without a computer connected.

In MicroPython, file management is straightforward — you can store, edit, and organize Python files directly on the device using Thonny IDE. Let’s go through how this works step by step.

Understanding the File System

Every MicroPython-enabled board includes a small internal file system stored in its flash memory. This file system behaves much like the folders on your computer, except it’s optimized for small embedded devices.

When you connect your board to Thonny, you’ll see two locations where you can save files:

  • This Computer: Your local storage — files stay on your PC or laptop.
  • MicroPython Device: The board’s internal storage — files here are stored in flash memory and can be executed directly by the board.

The device’s file system typically includes a few key files:

  • boot.py — runs every time the board starts up (handles setup or initialization tasks).
  • main.py — automatically executed after boot.py when the board powers on.
💡 Tip: Think of main.py as your “main program.” If you want your project to start automatically when powered, save it under this filename.

Saving Files in Thonny

Saving a file to your MicroPython device in Thonny is easy and only takes a few clicks.

  1. Open Thonny and connect your board.
  2. Click File → Save As...
  3. Choose MicroPython Device as the location.
  4. Enter a filename, for example, blink.py or main.py.
  5. Click OK to save.

You can now run this file anytime by opening it and clicking the green Run button or pressing F5.

⚙️ Note: If you save the file to This Computer, it will only exist on your PC and won’t run automatically on the device. To make it part of your board’s program, save it to the MicroPython Device.

Viewing and Managing Files

To view your MicroPython board’s storage, look for the Files panel in Thonny (usually on the left or right side). It displays a list of files stored on both your computer and the connected device.

From this panel, you can:

  • Upload files from your computer to the board.
  • Download files from the board to your computer.
  • Rename or delete files directly on the device.

These options make it easy to organize your MicroPython projects without using any command-line tools.

✅ Pro Tip: Keep your code files small and modular. Instead of one long main.py, break your logic into smaller helper files (like led_utils.py or sensor.py) and import them when needed.

Running Code Automatically on Boot

To have your program run automatically when the board powers on or resets, simply name your file main.py and save it to the device’s root directory.

Here’s what happens when the board starts up:

  1. The system executes boot.py (if it exists).
  2. Then it automatically runs main.py.

This means you can power your board using a USB adapter or battery, and your MicroPython program will begin running immediately — no computer required.

💡 Example:
If you saved your LED blink script as main.py, the LED will start blinking automatically each time the board powers up. Perfect for standalone projects!

Editing and Deleting Files

You can open any file on the device directly in Thonny to edit it. Just double-click the filename in the Files browser.

To delete a file, right-click it and choose Delete. Be careful when removing boot.py or main.py — these affect the board’s startup behavior.

⚠️ Warning: Deleting or overwriting boot.py or main.py can cause your project not to start automatically. Always keep backups of important scripts.

Checking Storage Space

Since most boards have limited flash memory, it’s a good idea to occasionally check how much space is left. You can do this directly in the REPL: 


>>> import os
>>> os.listdir()       # List files
>>> stat = os.statvfs('/')
>>> print("Free space:", stat[3] * stat[0], "bytes")

This command shows how many bytes are available in the file system — useful when managing larger projects.

Backing Up Your Code

You can back up your MicroPython scripts by downloading them from the device back to your computer using Thonny’s file panel. This ensures that your code is safe, even if the board is reset or reflashed.

✅ Tip: Keep a copy of your MicroPython files in a project folder on your computer. This makes it easy to sync versions, share projects, and restore files if needed.

Summary

File management is a fundamental part of working with MicroPython. Understanding how to save, edit, and organize your scripts will make your workflow smoother and your projects more reliable.

With Thonny’s built-in file tools, you can easily handle all these tasks without using command-line utilities. You’re now ready to build more complex projects that run independently on your board.

×


Related Articles: (by Series)