PlatformIO Community

How to define LittleFS partition, build image and flash it on ESP32?

Working on an ESP32 platform, SPIFFS is not workable for our needs and we want to use LittleFS as the virtual file system for our internal Flash memory. I can’t find information how I would have to define a LittleFS partition in PlatformIO, though I presume it would simply be some custom type.
Also, are there any good tools to create BIN images for LittleFS that PlatformIO can use and how would I tell PIO to use that tool and then flash the respective BIN file to the device?

I can’t seem to find any documentation that explains the path to set up custom partitions, their image creation and upload in PIO, so any suggestions or pointers would be really appreciated.

1 Like

So, I got a custom Python script to build my LittleFS partition image and I can upload it to the device using esptool, after all.
I’m still trying to figure out how to get PlatformIO to call the respective custom scripts, though, to build my image instead of a SPIFFS image when I select “Upload File System Image” and flash it to the device in the respective partition. Thoughts, anyone?

For all those interested, I solved the problem. I am essentially creating a SPIFFS partition and load my own LittleFS image into it instead, fooling PlatformIO into thinking, it’s actually dealing with a SPIFFS image. I am doing this by overloading the MKSPIFFS command.

I created a Python script that I call from platformio.ini

extra_scripts =

In this file I replace the MKSPIFFS tool command with my own like this

env.Replace( MKSPIFFSTOOL='python3" "' + env.get("PROJECT_DIR") + '/' )

My own tool now uses the command line arguments, builds the LittleFS bin image accordingly and saves it to where PlatformIO tells it to (the last argument in the mkspiffs call is the destination file name).

PlatformIO now believes it has actually created a SPIFFS.BIN file and proceeds to upload it to the device. Done!


Nice! I’ll add an issue to the github mentioning this, as LittleFS is missing from PIO at the moment as an FS option, for both ESP8266 and ESP32. Would you be willing to share your script also?

Edit: Er… now I’m confused… the ESP8266 core has LittleFS support as of 2.6.0, but not the ESP32 yet? Are you using a third party like esp32_littleflash or something?


I wrote my own Flash layer for LittleFS ( but the process is the same. Get info about the partition to determine the size, etc and use that info to initialize your LittleFS file system with. Couldn’t be simpler.

As for the script, you can find it below. The file copying is a bit awkward but shutil did not work for some reason and locked up, so I decided to really read each file into a buffer instead and save it out from there.

# This is a small tool to read files from the PlatformIO data directory and write
# them to a flashable BIN image in the LittleFS file format
# This script requires the LittleFS-Python mopackage
# Author: Guido Henkel
# Date: 1/2/2020
import getopt, sys
from littlefs import LittleFS
from pathlib import Path

print( "Building LittleFS image…" )

argList = sys.argv[1:]
arxx = { argList[i]: argList[i+1] for i in range(0, len(argList)-1, 2) }
print( arxx )

dataPath = arxx["-c"]                                                               # Grab the source path parameter

fileList = [pth for pth in Path(dataPath).iterdir() if pth.stem[0] != '.']          # Create a list of all the files in the directory

fs = LittleFS(block_size=4096, block_count=3072)                                    # Open LittleFS, create a 12MB partition

for curFile in fileList:
    print( "Adding " + )
    with open( curFile, 'rb' ) as f:                                                # Read the file into a buffer
        data =

    with, 'w') as fh:                                         # Write the file to the LittleFS partition
        fh.write( data )

outName = argList[-1]                                                               # The last argument is the destination file name
with open(outName, 'wb') as fh:                                                     # Dump the filesystem content to a file
1 Like