In this guide, you’ll learn how to install the ESP8266 LittleFS filesystem uploader plugin on Arduino IDE 2 (2.2.1 or higher) and how to upload files to the ESP8266 NodeMCU board filesystem.
Using an ESP32? Follow this tutorial instead: ESP32 with Arduino IDE 2 – Upload Files to the LittleFS Filesystem.
If you want to use LittleFS for the ESP8266 with VS Code + PlatformIO, follow the next tutorial instead:
Table of Contents
- Introducing LittleFS
- Installing LittleFS Filesystem Uploader Plugin
- Uploading Files to ESP8266 using the Filesystem Uploader
- Testing the ESP8266 LittleFS Uploader
If you’re still using Arduino 1.8, you can follow this tutorial instead: Install ESP8266 NodeMCU LittleFS Filesystem Uploader in Arduino IDE.
This plugin is also compatible with the ESP32 and Raspberry Pi Pico boards.
Introducing LittleFS
LittleFS is a lightweight filesystem created for microcontrollers that lets you access the flash memory like you would do in a standard file system on your computer, but it’s simpler and more limited. You can read, write, close, and delete files. Using LittleFS with the ESP8266 boards is useful to:
- Create configuration files with settings;
- Save data permanently;
- Create files to save small amounts of data instead of using a microSD card;
- Save HTML, CSS, and JavaScript files to build a web server;
- Save images, figures, and icons;
- And much more.
Installing the LittleFS Uploader Plugin on Arduino IDE 2
To upload files to the ESP8266 on Arduino IDE 2, we’ll use this LittleFS Uploader plugin that is compatible with Arduino 2.2.1 or higher and can be used for the ESP8266, ESP32, and Raspberry Pi Pico boards.
Windows Instructions
Follow the next steps to install the filesystem uploader if you’re using Windows (click here for MacOS instructions):
1) Go to the releases page and click the .vsix file to download.
2) On your computer, go to the following path: C:\Users\<username>\.arduinoIDE\. Create a new folder called plugins if you haven’t already.
3) Move the .vsix file you downloaded previously to the plugins folder.
4) Restart or open the Arduino IDE 2. To check if the plugin was successfully installed, press [Ctrl] + [Shift] + [P] to open the command palette. An instruction called ‘Upload Little FS to Pico/ESP8266/ESP32‘ should be there.
That means the plugin was installed successfully. Proceed to this section to test the filesystem uploader plugin.
Mac OS X Instructions
Follow the next steps to install the filesystem uploader if you’re using Mac OS X:
1) Go to the releases page and click the .vsix file to download.
2) In Finder, type ~/.arduinoIDE/ and open that directory.
3) Create a new folder called plugins.
4) Move the .vsix file to the plugins folder.
5) Restart or open the Arduino IDE 2. To check if the plugin was successfully installed, press [⌘] + [Shift] + [P] to open the command palette. An instruction called ‘Upload LittleFS to Pico/ESP8266‘ should be there (just scroll down or search for the name of the instruction).
Uploading Files to ESP8266 NodeMCU using the Filesystem Uploader in Arduino IDE 2
To upload files to the ESP8266 NodeMCU filesystem, follow the next instructions.
1) Create an Arduino sketch and save it. For demonstration purposes, you can save an empty sketch.
2) Then, open the sketch folder. You can go to Sketch > Show Sketch Folder. The folder where your sketch is saved should open.
3) Inside that folder, create a new folder called data.
4) Inside the data folder is where you should put the files you want to upload to the ESP8266 filesystem. As an example, create a .txt file with some text called test_example.txt.
5) In the Arduino IDE, in the Tools menu, select the desired flash size (this will depend on the size of your files).
6) Make sure you have the right board (Tools > Board) and COM port selected (Tools > Port).
7) Then, upload the files to the ESP8266 board. Press [Ctrl] + [Shift] + [P] on Windows or [⌘] + [Shift] + [P] on MacOS to open the command palette. Search for the Upload LittleFS to Pico/ESP8266 and click on it.
Important: ensure the Serial Monitor is closed. Otherwise, the upload will fail.
After a few seconds, you should get the message “Completed upload. “. The files were successfully uploaded to the ESP8266 filesystem.
Troubleshooting
If you get the following error message “ERROR: No port specified, check IDE menus“, restart the Arduino IDE, and try again.
Testing the ESP8266 LittleFS Uploader
Now, let’s check if the file was saved into the ESP8266 filesystem. Upload the following code to your ESP8266 NodeMCU board.
#include "LittleFS.h"
void setup() {
Serial.begin(115200);
if(!LittleFS.begin()){
Serial.println("An Error has occurred while mounting LittleFS");
return;
}
File file = LittleFS.open("/test_example.txt", "r");
if(!file){
Serial.println("Failed to open file for reading");
return;
}
Serial.println("File Content:");
while(file.available()){
Serial.write(file.read());
}
file.close();
}
void loop() {
}
After uploading, open the Serial Monitor at a baud rate of 115200.
Press the ESP8266 on-board “RST” button. It should print the content of your .txt file in the Serial Monitor.
You’ve successfully uploaded files to the ESP8266 filesystem using the plugin.
Wrapping Up
In this tutorial, we’ve shown you how to upload files to the ESP8266 LittleFS filesystem on Arduino IDE 2 using an uploader plugin.
We’ve shown you how to upload a .txt file, but you can upload other file formats like HTML, CSS, and Javascript files to build a web server, images, or small icons, save configuration files, etc.
We have a project example in which we build a web server using HTML and CSS files saved on the filesystem (simply replace SPIFFS with LittleFS).
If you want to learn more about the ESP8266, check our resources:
- Home Automation using ESP8266
- SMART HOME with Raspberry Pi, ESP32, ESP8266
- Build Web Servers with ESP32 and ESP8266
- Firebase Web App with ESP32 and ESP8266
- More ESP8266 NodeMCU Projects and Guides…
Thanks for reading.
I’m not sure I understand the gist of this article.
Are you saying that if someone wants to use the littleFS with an ESP32, they are constrained to use Arduino IDE 1.8.x instead of version 2.x.x of the Arduino IDE?
Regards,
Ray
No. IDE 2.x works fine with ESP32. You just can’t directly upload files to the LittleFS file system with it. I get around this by having a routine in the setup section so that, upon booting, it checks for an SD card. If the card is found various files are copied to the file system. Operationally this is better because you can change the files in the field with no computer. I use an INI file to provide wifi credentials and other data so I just need an SD card for each site.
Hi.
Yes. At the moment, there isn’t support for the ESP32 Uploader Plugin on Arduino 2.
You can use the command line on your computer, VS Code, or the old Arduino IDE.
Regards,
Sara
If you have the knowledge how to do it from commandline
Might be nice to add it to this article or create a new
You site is ammazing
Sara,
Thanks for your answer.
Ray
Hi, I always follow you guys, you are the best, thanks for your work, it is supposed to work now on esp32: https://github.com/earlephilhower/arduino-littlefs-upload/releases/tag/1.1.5
Hi.
That’s great!
Thanks for letting me know. I’ll test it and create a tutorial about it ASAP.
Regards,
Sara
I have tested it and works good.
Thanks to you
I tried to use it for TFT_eSPI_OpenWeather_LittleFS which puts all the icons, fonts, etc. into folders. Upon checking, all the folders were empty. Apparently it only copies root level items. I made a sketch that copies all files and folders from an SD card to the LittleFS file system. It can be found here:
https://www.mulvey.us/Copy_SD_to_LittleFS.zip
You need to partition the file system the same way you will use it in the final sketch.
It also does a touchCalibrate and saves the calibration file. You can REM out that command if you don’t need it.
nice
but
cannot get it to work on Linux Mint ide2
and want also ESP32 for my project
so switch to arm ide 1 on raspberry pi400
https://ldijkman.github.io/async-esp-fs-webserver/
A fatal esptool.py error occurred: could not open port ‘COM6’: PermissionError(13, ‘Access is denied.’, None, 5)
Hi.
Close the serial monitor and any other instances of the Arduino IDE.
Regards,
Sara
I failed to notice an open , but unused instance of the serial monitor.
Thank you Sara.
Small typo / glitch?
This line :
2) On your computer, go to the following path: C:\Users.arduinoIDE.
should be
2) On your computer, go to the following path: C:\Users\.arduinoIDE.
darn – formatting screwed up. What I tried to post is that the Window’s user name needs to go between the C:\Users and the .arduinoIDE part of the path
Hi.
Thanks.
Yes, you’re right.
Thanks for letting me know.
I already fixed it.
Regards,
Sara
…and what are the Pro’s and Con’s of LittleFS over SPIFFS…?
The second sentence of this article just let me ask why I would want to use this at all. -Just the information I expect in the introduction of this filesystem.
It does work on Windows10. The appearing in the ctrl+sh+p may or may not show it. Type upload in the search window and it appears.
Amazing site, I keep coming back here, as it’s filled with working examples, I just cannot find anywhere else – absolutely brilliant! 🙂
Instead of opening a file, I want to open a html very simple default web page that I have uploaded
file = LittleFS.open(“/test_example.txt”, “r”);
so I need my file to read like this File file = LittleFS.open(“/menu.html”, “r”);
but of course, that displays the contents of my HTML file. Instead, I need my local browser to open it.
Is there an easy way to do this, so if someone goes to the local ip address of my microprocessor, I can put a default web page/ menu instead of just some text ?
I am using a NodeMCU (4mb Flash) with IDE v2+ and I can successfully get the text file to upload and be displayed!
Many thanks for your time and your great site!
🙂
Hi.
Check this tutorial: https://randomnerdtutorials.com/esp8266-web-server-spiffs-nodemcu/
In the code, instead of “SPIFFS” use “LittleFS”.
This example shows how to display the files saved on LittleFS on a web page that you access when you go to your board IP address..
Regards,
Sara
Great article thanks. Trying to get this running on an ESP8266 (12F) but I get compile error:
SPIFFS No such file or directory.
After googling, it looks like LittleFS should be used.. Tried replacing SPIFFS with LittleFS in code but loads more errors.
Any suggestions?
Thanks
Yeah. Best news lately.
What errors did you get?
You just need to replace the word “SPIFFS” with “LittleFS”
Make sure you have your libraries updated as well as the ESP8266 boards in Tools > Boards > Boards Manager.
Regards,
Sara
Hi Sara,
Great tutorial thanks.
I followed it all the way through – no issues, everything appeared to work.
would not read the files. “Failed to open file for reading” was all I got.
I am using windows, Arduino IDE 1.8.19
Wemos D1 R2 [not a mini]
After much head banging I have proved most of it works … NOT as expected:
The upload seems to be adding suffixes to the file names.
but now I have proved the text in the files is uploaded correctly.
I have checked my files in ‘data’ file names are:
“test_example.txt”
“file1”
Essentially I am using the program file supplied above, I have added some prints and some extra code at the end to try and understand what is going wrong. OUTPUT TO SERIAL IS :
<
“lots of unprintable and extended char which wont copy & paste which is not exact the same every time then I get”
LitFS_test on Wemos Serial.begin@115200 Aug24 <- my line of print
after Serial.begin()
Failed to open file for reading 1
Failed to open file for reading 2
File Content:
===================== <– my print sttmnt
file1.txt44
file 1
a test file in text format
Aug 2024
test_example.txt.txt55
This is testing text
in littleFS_test.txt
I dun it.
>
I dont understand the unprintables, its like wrong baud rate, but that doesnt make sense because prints everything else fine. It does seem to occur before serial.begin().
Most of it is the text in my text files and is correct.
The file names ??? as you may see :
“file1” has become “file1.txt44”
“test_example.txt” has become “test_example.txt.txt55”
Sorry I have not done a good job of formatting the output, I assure you, my problem is the filename is changed between the data folder and the littleFS
Thank you for any further assistance / guidance
Update:
I solved some of my problems:
changed all baud rates to 74880 removed the gibberish
the WEMOS is printing
” ets Jan 8 2013,rst cause:2, boot mode:(3,7)
load 0x4010f000, len 3424, room 16
tail 0
chksum 0x2e
load 0x3fff20b8, len 40, room 8
tail 0
chksum 0x2b
csum 0x2b
v00049680
~ld
” when it boots up. if anyone can explain I would be greatful.
The uploaded file names did not have digits on the end just and extra “.txt”
File file = LittleFS.open(“test_example.txt.txt”, “r”);
is the line of code I had to use to read the file as per your code presented in this tutorial.
Thanks
Lobie