How to Upload Files to ESP32 LittleFS File System

Working with file systems like LittleFS on the ESP32 is essential for projects that require storage of configuration files, web server assets (HTML, CSS, JS), or data logs. LittleFS provides a reliable and efficient way to store files in the ESP32's flash memory, enabling developers to create more versatile and capable applications.

In earlier versions of the Arduino IDE, uploading files to LittleFS was made easy with the help of a .jar plugin that integrated directly with the IDE. However, with the evolution of the Arduino IDE — especially version 2.x and later — this plugin has become outdated and incompatible. As a result, many developers are left without a direct, GUI-based method to manage LittleFS files in modern setups.

But not to worry — the ESP32 core already includes the necessary tools to upload files to LittleFS, even without IDE plugins. These tools can be accessed and run manually using the command line, offering a simple and effective alternative.

This guide walks you through the step-by-step process of uploading files to the ESP32's LittleFS using the Command Prompt (or terminal on Linux/macOS). Whether you're developing a web interface for your IoT device or storing runtime data, this method ensures you can continue to use LittleFS efficiently with the latest ESP32 tool-chains and Arduino IDE versions.

Let’s dive in!

Git repository: https://github.com/Yadukrishnan-KM/esp32-LittleFS-file-upload-using-terminal4new-ArduinoIDE

Tested and Succeeded on:

1. Operating System: Ubuntu 22.04.5 LTS
2. Arduino IDE Version: 2.3.6
3. ESP32 Arduino Core Version( by Espressif): 3.2.1

1. Open Arduino IDE 2.3.6.
2. Open File > Preferences.
3. Check the box for "Show verbose output during: [X] compilation [X] upload". Click OK.
4. Create a new project using the given example code
5. Enable the debug and select full debug from the Arduino tool drop down menu
6. Enable serial monitor (@ correct baud rate) for seeing the debug messages
7. Choose correct board and COM port (My case: ESP32 DevKit V1 and /dev/ttyUSB0)
8. Compile and upload

Observe the verbose output in the Arduino IDE console during compilation and upload. Look for the serial port (e.g., /dev/ttyUSB0) and keep the IDE open for now.

First need to confirm which partition scheme is being used by your selected board. It is required for finding the memory address of spiffs partition start and its size.

Method A: Inspect boards.txt (Recommended)

This file explicitly defines the partition scheme for each board (you can use terminal or file explorer UI, Here explaining terminal method)

1. Open your terminal.
2. Navigate to your ESP32 core installation directory:

cd ~/.arduino15/packages/esp32/hardware/esp32/3.2.1/

(# IMPORTANT: Adjust '3.2.1' if your ESP32 core version is different.)

1. Open boards.txt with a text editor: (terminal command: gedit boards.txt &)
2. Find your board's definition. (My case: doitESP32devkitV1)
3. Look for the build.partitions line. This line specifies the .csv file used for the default partition scheme.
4. Example: esp32.menu.PartitionScheme.default.build.partitions=default.csv

This confirms that default.csv is being used for the default partition scheme.

Method B: Analyze Verbose Upload Output (or if you are enabled the full debug options from tools option in Arduino IDE, it will show on serial monitor after successfull upload of sketch)

The verbose output during sketch upload can also reveal the partition table used.

1. In Arduino IDE 2.3.6, upload your sketch again (from Step 1).
2. Review the verbose output in the black console area.
3. Search for partition or partition_table.bin. You might see a line similar to this (though paths and exact filenames can vary):

...write_flash 0x8000 /home/thepasswordisiitdh123/.arduino15/packages/esp32/hardware/esp32/3.2.1/tools/partitions/default_partition_table.bin

This indicates that default_partition_table.bin (generated from default.csv) is being flashed.

Now that you've confirmed the .csv file (likely default.csv), let's get the exact LittleFS partition details. (explaining terminal method, you can use file explorer UI)

1. Open your terminal.
2. Navigate to your ESP32 core's partitions directory:

cd ~/.arduino15/packages/esp32/hardware/esp32/3.2.1/tools/partitions/

(# IMPORTANT: Adjust '3.2.1' if your ESP32 core version is different.)

1. Open the identified .csv file (e.g., deesptool.py --chip esp32 --port /dev/ttyUSB0 write_flash 0x290000 littlefs.binfault.csv) with a text editor (terminal command: gedit default.csv & ) (change file name if required)
2. Locate the spiffs data partition. Note its Offset (flash address) and Size.

From your previous output, this is: (My case)

Offset (FLASH_ADDRESS): 0x290000

Size (FILESYSTEM_SIZE): 0x160000

These values will be used in subsequent commands.

Now we need to make a file system image for uploading our required files to esp32 flash (spiffs)

"esptool.py" is using as the flasher and the "mklittlefs" using as the image file maker (both are available in the espcore my case:~/.arduino15/packages/esp32/tools)

For using these tools we need some basic python tools, the terminal commands are given below,

1. Install python3-pip (if not already installed):

sudo apt update

sudo apt install python3-pip

1. Install esptool:

pip install esptool

1. esptool available from internet using the above command or you can use the one present in espcore folder using the given method which we are going to use for mklittlefs. mklittlefs is not able to download from internet
2. Locate mklittlefs: This tool is usually bundled with the ESP32 Arduino core.

cd ~/.arduino15/packages/esp32/tools/mklittlefs/3.0.0-gnu12-dc7f933/

1. # Replace '3.0.0-gnu12-dc7f933' with your actual version

Note the full path to mklittlefs (e.g., ~/.arduino15/packages/esp32/tools/mklittlefs/3.0.0-gnu12-dc7f933/mklittlefs). You'll use this path in the next step.

(Optional for convenience): Add this path to your system's PATH environment variable in ~/.bashrc to run mklittlefs directly. Terminal command given below, or you can open the file and add the path manually

echo 'export PATH="$PATH:/home/thepasswordisiitdh123/.arduino15/packages/esp32/tools/mklittlefs/3.0.0-gnu12-dc7f933/"' >> ~/.bashrc

source ~/.bashrc

Create a data folder inside your sketch directory and place your files there.

1. Navigate to your sketch directory:

cd ~/Desktop//My_projects/ESP32-littleFS/

1. Create the data subfolder and create some files (my case: txt files), you can you terminal also - commands given below

mkdir -p data

echo "This is the first line of text." > data/file1.txt

echo "Second file content here." > data/file2.txt

echo "A third file for LittleFS." > data/file3.txt

1. Your sketch folder should now look like:

ESP32-littleFS/

├── ESP32-littleFS.ino

l---------- data/

l---------- file1.txt

l---------- file2.txt

l---------- file3.txt

Use mklittlefs to create the flashable image from your data folder.

1. Ensure you are in your sketch directory:

cd ~/Desktop/My_projects/ESP32-littleFS/

1. Run the mklittlefs commands in terminal:

# If you added mklittlefs to PATH in step 4:

mklittlefs -c data -s 0x160000 -p 0x100 littlefs.bin

# OR, if not in PATH, use the full path:

~/.arduino15/packages/esp32/tools/mklittlefs/3.0.1/mklittlefs -c data -s 0x160000 -p 0x100 littlefs.bin

Note: 0x160000 is the FILESYSTEM_SIZE from Step 3.

littlefs.bin will be created in your current sketch directory.

Use esptool.py to upload the generated .bin file to the ESP32's flash memory.

1. Close the Serial Monitor in Arduino IDE.
2. Identify your ESP32's serial port (e.g., /dev/ttyUSB0 from Step 1).
3. Run the esptool.py command:

esptool.py --chip esp32 --port /dev/ttyUSB0 write_flash 0x290000 littlefs.bin

Note: Replace /dev/ttyUSB0 with your actual serial port.

0x290000 is the FLASH_ADDRESS (Offset) from Step 3.

When esptool.py shows "Connecting...", press and hold the "BOOT" button on your ESP32 board. Release it once the flashing percentage starts to appear.

Finally, upload your sketch (if note done previously) and check the Serial Monitor to confirm the files are present.

1. Open the Serial Monitor (Tools > Serial Monitor).
2. Set the baud rate to 115200 (or set yours).
3. Restart the board by pressing the onboard reset button

You should now see the output from your sketch, listing the file1.txt, file2.txt, and file3.txt that you uploaded via the command line!

Done....