Before you get started you'll want to be familiar with the basics of using MicroPython by reading these guides:

• MicroPython Basics: What is MicroPython?
• MicroPython Basics: How to Load MicroPython on a Board
• MicroPython Basics: Load Files & Run Code
• MicroPython Basics: Loading Modules

Note that SD card support varies greatly for MicroPython boards. A few boards have good native support built-in:

pyboard

The pyboard is one of the easiest MicroPython boards to use with a microSD card.  The board is built with a small microSD card slot and its firmware will automatically load the card as the root filesystem for the board.  Plug in the card, power up the pyboard and it should automatically use the card as a filesystem to run scripts, store data, etc. You don't need to buy extra hardware or run any commands! 

Check out the pyboard SD card documentation for more details.

WiPy

The WiPy also makes it easy to use a microSD card with its WiPy expansion board.  The expansion board includes a microSD card slot so you can easily plug in a card.  With a few lines of code you can mount the microSD card on the board's filesystem to read and write data, just like with the pyboard.

Check out the WiPy SD card documentation for more details.

Other MicroPython boards like the ESP8266 need to use a little more code to work with microSD cards.  Follow the steps below to use MicroPython ESP8266 with a microSD card.

MicroPython ESP8266 SD Card Setup

Before you can use a microSD card with MicroPython on the ESP8266 you'll need to make sure you're using at least firmware version 1.8.4 or higher.  If you aren't familiar with loading MicroPython firmware on the ESP8266 check out this handy guide for all the details.  Be sure to get MicroPython ESP8266 stable firmware version 1.8.4 or higher from its download page!

Once your board is running MicroPython 1.8.4 or higher there's one more step to enable microSD card access.  You need to manually install a Python module to talk to the SD card.  This module is not included in the MicroPython ESP8266 firmware by default, but it's easy to copy to the board's internal filesystem. Be sure to read this guide on loading modules to understand more about how you can copy modules and load them.

The quickest way to load the module is to copy its source to the board.  This isn't the most memory efficient way to load the module (it will use a bit more RAM), but it's good to quickly get started.  Once you have SD card access working you can freeze the module into a custom build of MicroPython firmware to reduce its memory usage.

First download the SD card driver module from the MicroPython GitHub repository by clicking the button below:

Next use a tool like ampy to copy the sdcard.py file to the root of the board's filesystem:

At this point the sdcard.py file should be on the root of the MicroPython board's filesystem.  You're ready to run code that can import the SD card and make it the new root filesystem.

Mount SD Card

To mount the SD card as the MicroPython ESP8266 board's filesystem you'll need to run a few commands.  Connect to the board's serial or other REPL and first run this import command:

If you see an error like the sdcard module couldn't be found or imported double check that you copied the module's .py file to the board (or that you froze it into the firmware if you're building a custom MicroPython firmware).

Once the necessary modules are imported you can initialize access to the SD card with this command:

Make sure you're using MicroPython ESP8266 version 1.8.4 or higher!  If you're using an older firmware version this command will fail because the machine.SPI object doesn't use interface number 1.

This command will create a SD card object that's initialized using the hardware SPI interface (interface 1 for the ESP8266) and the specified chip select pin (GPIO 15, but you can use other GPIO pins if you wire them accordingly).

Next to make the SD card the new root filesystem run the following command:

This line will create a new virtual FAT filesystem using the SD card as a backing store instead of the internal flash memory on the board.  The filesystem is assigned to a global vfs object that MicroPython ESP8266 internally uses for its filesystem.  

It actually isn't that important that the vfs object be assigned since the VfsFat object initializer does all the work to mount the filesystem.  However as a best practice it's good to assign the new VfsFat object to a variable so it never gets garbage collected.

The second parameter to the VfsFat object initializer is the path on the filesystem to mount the card.  For now only the empty string is allowed as it specifies to load the filesystem as the new root (i.e. under / ).

At this point the microSD card should be the new root filesystem for the board.  You can interact with the files just like interacting with files on the internal filesystem.  See the CircuitPython file usage page for details on file reading and writing with the open, read, and write functions.  Remember since the card is mounted as the root filesystem you access files directly under the / path and not /sd or other deeper paths!