In this tutorial, you’ll learn how to install the ESP8266 LittleFS Filesystem Uploader Plugin in your Arduino IDE to upload files to the ESP8266 NodeMCU filesystem.
If you want to use LittleFS for the ESP8266 with VS Code + PlatformIO, follow the next tutorial instead:
Are you using Arduino IDE 2? Follow this tutorial instead: Arduino IDE 2: Install ESP8266 NodeMCU LittleFS Uploader (Upload Files to the Filesystem).
Table of Contents
- Introducing LittleFS
- Installing LittleFS Filesystem Uploader Plugin
- Uploading Files to ESP8266 using the Filesystem Uploader
- Testing the ESP8266 LittleFS Uploader
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 especially 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 LittleFS Filesystem Uploader Plugin
You can create, save and write files to the ESP8266 filesystem by writing the code yourself on the Arduino IDE. This is not very useful because you’d have to type your files’ content in the Arduino sketch.
Fortunately, there is a plugin for the Arduino IDE that allows you to upload files directly to the ESP8266 LittleFS filesystem from a folder on your computer. This makes it easy and straightforward to work with files.
SPIFFS is currently deprecated and may be removed in future releases of the ESP8266 core. It is recommended to use LittleFS instead. LittleFS is under active development, supports directories, and is faster for most operations. The methods used for SPIFFS are compatible with LittleFS, so we can simply use the expression LittleFS instead of SPIFFS in our code.
Windows Instructions
Follow the next steps to install the filesystem uploader if you’re using Windows:
1) Go to the releases page and click the ESP8266LittleFS-X.zip file to download.
2) Find your Sketchbook location. In your Arduino IDE, go to File > Preferences and check your Sketchbook location. In my case, it’s in the following path: C:\Users\sarin\Documents\Arduino.
3) Go to the sketchbook location, and create a tools folder.
4) Unzip the downloaded .zip folder. Open it and copy the ESP8266LittleFS folder to the tools folder you created in the previous step. You should have a similar folder structure:
<Sketchbook-location>/tools/ESP8266FS/tool/esp8266fs.jar
5) Finally, restart your Arduino IDE.
To check if the plugin was successfully installed, open your Arduino IDE and select your ESP8266 board. In the Tools menu, check that you have the option “ESP8266 LittleFS Data Upload“.
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 ESP8266LittleFS-X.zip file to download.
2) Unpack the files.
3) Create a folder called tools in /Documents/Arduino/.
4) Copy the unpacked ESP8266LitlteFS folder to the tools directory. You should have a similar folder structure.
~Documents/Arduino/tools/ESP8266FS/tool/esp8266fs.jar5) Finally, restart your Arduino IDE.
To check if the plugin was successfully installed, open your Arduino IDE. Select your ESP32 board, go to Tools and check that you have the option “ESP8266 LittleFS Data Upload“.
Uploading Files to ESP8266 using the Filesystem Uploader
To upload files to the ESP8266 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 save into the ESP8266 filesystem. As an example, create a .txt file with some text called test_example.
5) In the Arduino IDE, in the Tools menu, select the desired flash size (this will depend on the size of your files).
6) Then, to upload the files in the Arduino IDE, you just need to go to Tools > ESP8266 LittleFS Data Upload.
Important: ensure the Serial Monitor is closed. Otherwise, the upload will fail.
After a few seconds, you should get the message “LittleFS Image Uploaded “. The files were successfully uploaded to the ESP8266 filesystem.
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 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 on the Serial Monitor.
You’ve successfully uploaded files to the ESP8266 filesystem using the plugin.
Wrapping Up
Using the filesystem uploader plugin is one of the easiest ways to upload files to the ESP8266 filesystem. In this tutorial, 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
- Build Web Servers with ESP32 and ESP8266
- Firebase Web App with ESP32 and ESP8266
- More ESP8266 NodeMCU Projects and GuidesâŠ
Thanks for reading.
What are the advantages and disadvantages of using LittleFS on esp8266?
Hi Gary.
You can learn more about SPIFFS vs LittleFS here: https://arduino-esp8266.readthedocs.io/en/latest/filesystem.html#spiffs-and-littlefs
Regards,
Sara
im sort of having a problem here;
i did everything the page asked me to do but i get an error
littleFS Error: mklittlefs not found!
can you help me to solve this problem
Hi.
See that issue here: https://rntlab.com/question/littlefs-error-mklittlefs-not-found/
Regards,
Sara
Install LittleFS on MacOS
Download:
https://github.com/earlephilhower/arduino-esp8266littlefs-plugin/releases/download/2.6.0/ESP8266LittleFS-2.6.0.zip
Unzip:
/Applications/Arduino.app/Contents/Java/tools
Download:
https://github.com/earlephilhower/mklittlefs/releases/download/3.0.0/x86_64-apple-darwin14-mklittlefs-295fe9b.tar.gz
Unzip file mklittlefs and rename mklittlefs.py
Copy file mklittlefs.py
/Users/âŠâŠâŠ../Library/Arduino15/packages/esp8266/hardware/esp8266/2.7.4/tools
Thank you very much. This cracked it.
Having put the tool/esp8266littlefs.jar in every Arduino directory on my Mac with no joy, the clincher was the mklittlefs.py. And of course not to waste time opening Arduino IDE 2.x after you have put the correct files in the Arduino 1.x structure.
Hello
I’m reading your comments well.
I found that esp01 (esp8266ex) is available.
However, we confirmed that we couldn’t do it due to a lack of EEPROM and found a solution to this.
First, I purchased 25Q128FV (16MB), changed the chip, and then confirmed that it was built.
After replacement, flash upload should be performed using flash_download_tool_v3.8.5, and ESP8266_NONOS_SDK-3.0.4.
Please refer to https://www.programmersought.com/article/93971480386/ for a brief explanation.
0xFFB000 : blank.bin
0xFFC000 : esp_init_data_default.bin (e.g. : esp_init_data_default_v08.bin)
0xFFE000 : blank.bin
0x10000 : eagle.irom0text.bin (e.g. : user1.2048.new.5.bin)
0x00000 : eagle.flash.bin (e.g. : boot_v1.7.bin)
I installed the tool following the your tut. There is no LittleFS for esp8266 in my library or github, only for esp32. Evidently, something has changed since the article was written.
Is there a solution?
Hi.
I didn’t understand the issue.
What has changed?
Regards,
Sara
Turns out the part you left out is “you MUST be using esp8266 3.0.2”, 3.0.1 is not going to do it.
For some reason I had to uninstall Arduino IDE and physically remove the c:\users/me/appdata/local/arduino15 directory and re install the IDE and boards.
All is well now.
Thank you
When I first tried to upload files to LittleFS, it repeatedly failed to connect to the ESP8266 via the COM port with an error message:
esptool.FatalError: Failed to connect to ESP8266: Timed out waiting for packet header
LittleFS Upload failed!
After searching for solutions, I finally found another site that mentioned the board must be put into flash mode (if it does not automatically do that) to upload files to LittleFS. It might be worth adding a note in the instructions on this page to indicate that the board must be in flash mode to upload files. It might save others a lot of time researching this problem.
is there a way to combine LittleFS with the main code and have one burning BIN file for uploading using ESP download tool ?
Why my ESP8266 forgets files ?
Despite following the instruction of the entire instruction, I do not get an option Tools > ESP8266 Sketch Data Upload.
Hi.
That probably means that there’s something wrong with your installation.
Are you sure you installed it correctly?
Some people have more than one Arduino ide installation, and then happen to install the tool on the other installation and not on the one they’re using.
Regards,
Sara
sevarel done. Also follwed a video how to do this. All with no succes. No Tools > ESP8266 Sketch Data Upload. Als new ESP8266LittleFS tried. No option in IDE.
Which version of Arduino IDE are you using?
Regards,
Sara
I had found another old arduino and removed it. PC restarted, no always no option. After this Again the new (2.04) arduino installed, no option. Removed everything and restarted PC. After this, completely new installation was carried out. Still not an option.
D:\Documents\Arduino\tools\ESP8266FS\tool\esp8266fs.jar
So don’t understand why I don’t get an option to upload data
I think I’ve found the problem. I installed an old version on a laptop (1.8) Everything works now. Tried this on my PC and everything is present. If I install the new 2 version again, the option is not present. The question now is, how do I get the option with version 2 of arduino
Hi.
Unfortunately, at the moment, there isn’t a tool to upload to SPIFFS on Arduino 2.0.
Regards,
Sara
I installed everything following the instructions, and even tried several versions from github, but no chance. Tried this on two laptops, one with only the old IDE (1.8.19) and python2.7, and the other with old IDE and paralel the new one (2.0.4. or something alike) under Windows 10.
Installing an earlier version for the old SPIFFS works, so I am in the right directory and obviously got the instructions right. But I’d prefer to use the newer LittleFS.
In the versions adapted for LittleFS (2.5.1 or 2.6.0) on github I noticed that there is no /tools/xy.jar-File, but only a /src/xy.java. So both the path AND the file type differ from the instructions.
There is a makefile included in the zips, which seems to generate a jar from the java file, but it’s a shell script for linux (and uses linux paths), so useless under windows. Furthermore I noticed in the diffs on github that python3 seems to by required – I just had to downgrade my system to python2.7, which was requested in some docs for OTA functionality (but as now comes to my mind it worked also on the python3-laptop, so may have been a wrong requirement, or the OTA scripts run with both versions).
Any ideas? Or better a link to a webserver which allows to explore the LittleFS? Thanks in advance!
Hi.
Currently, this doesn’t work with Arduino 2.0.
But this works for arudino 1.8.x
Do you ever get the “LittleFS Data Upload” option in the Arduino menu?
Regards,
Sara
Hi Sara
it’s me again, after quite some time ….
Probably i have found the problem behind the missing âLittleFS Data Uploadâ option !!
When someone follows the description to unzip the downloaded “ESP8266LittleFS-2.6.0)” and then moves the unzipped firle to the “tools” section, you will get one folder too much. So when I copied the content of ESP8266LittleFS-2.6.0 to tools/ESP8266LittleFS (like you correctly show in your screenshot), the option pops up correctly.
I hope this will help our fellow “makers” …
Best regards from Germany
Jos
Great!
I’m glad it’s working.
Thanks for the follow-up.
Regards,
Sara
Hi Sara, thanks for the fast reply!
Yes and no. The data upload function only works with the old SPIFSS version (ESP8266FS-0.1.3.zip). When I remove this and instead try the versions 2.5.1 or 2.6.0 (“Modified by Earle F. Philhower, III for LittleFS use”), nothing shows up. So the destination should be correct.
In github it says:
“Unpack the tool into tools directory (the path will look like /Arduino/tools/ESP8266LittleFS/tool/esp8266littlefs.jar”
But the downloaded zips (2.5.1 upwards) don’t contain a file “esp8266littlefs.jar”, but a “ESP8266LittleFS.java”). And the path in the zip is not “/tools”, but “/src”. So I guess I somehow get the wrong archive?
Regards,
Atouk
Sorry, please cancel my request. After writing my last post it reluctantly crawled to my mind that obviously I downloaded the wrong zip.
I am not very experienced with github and so far was used to click on “code” (upper left) to get a download menue. This worked fine with some arduino libs. I didn’t notice that the “releases” section to the right does NOT contain old versions, but instead is the easter-eggish place to download.
Where are the good old days where people placed a big, fat “download” button for old-fashioned single-core-minded guys like me?
// dumb mode off
Hi Sarah,
Thanks for the post and for your reply to the comment. I would like to ask if it is possible to put ESP8266LittleFS on the current version of Arduino IDE 2.1.0?
Best regards,
Gulbutta
Hi.
Not yet.
As far as I’m concerned, there isn’t a plugin for Arduino IDE 2.0 at the moment.
Regards,
Sara
Thank you, Sara.
I have solved the problem by downlowding the Arduino IDE 1.8.
Best regards,
Gulbutta
Great!
Hello team,
I hope this message finds you well. Good morning on October 5th, which happens to be a Thursday. I wanted to inform you about an important update regarding our LittleFS article.
Recently, there has been a change in the LittleFS setup. Instead of a single jar file, we now have three separate class files. I kindly request you to please review the article and make the necessary updates to reflect this change. I attempted to incorporate these three files in the same manner as before, but unfortunately, it did not yield the expected results. I’m also currently stuck as I couldn’t get it to work.
I believe that updating the article to accommodate these three class files will not only benefit the current readers but also make the information more accurate and up-to-date. This change will be especially helpful for those who visit the article in the future.
Thank you
Hi.
I’m sorry. But I didn’t understand your issue.
The file you need to download from this page: https://github.com/earlephilhower/arduino-esp8266littlefs-plugin/releases is the one called ESP8266LittleFS-2.6.0.zip
Regards,
Sara
There is a IDE 2 plugin that seems to work fine now (29 Oct 2023) for my case :
– IDE 2.2.1
– Board ESP8266 Wemos D1 Mini clone
https://github.com/earlephilhower/arduino-littlefs-upload/tree/main
The installation is a bit different than described in this article :
I had to compile / restart a few times but then is was OK.
Hi.
Great.
Thanks for sharing.
Do you know if that works for ESP32 too?
Regards,
Sara
I created a folder Arduino IDE\plugins and placed the file arduino-littlefs-upload-1.1.5.vsix there
I also tried various options and nothing helps me, the âfile upload buttonâ does not appear
but it didnât help me Arduino version 2.3.2
Hi.
If you’re using Arduino IDE 2, this is the tutorial you need to follow: https://randomnerdtutorials.com/arduino-ide-2-install-esp8266-littlefs/
Regards,
Sara
Hi Sara, A few years ago I built a temp/humidity sensor for my wife’s greenhouse. Due to some issues I still haven’t figured out, I couldn’t get the ESP8266 to serve bothe the index, and a background image (both saved using SPIFFS). So I left the image in spiffs, and built the html into the sketch. It worked; much has changed since then, like SPIFFS being deprecated, and the arduino IDE 2.xx incompatability with LittleFS. I have both the latest IDE and the version that supposedly supports LittleFS on a system. Using the IDE 1.8.16 I can install the LittleFS plugin, and it appears to function, but the images are not displayed. When using your example to serve images (https://randomnerdtutorials.com/display-images-esp32-esp8266-web-server/) The title is served but only place holders for the images. I have tried to serve a text file with the same results. At this point I’m lost. Any help would be greatly appreciated.
Hi.
If you open the JavaScript console on the web server page, do you get any errors?
Regards,
Sara
Hi Sara thanks for the response, I know you guys are busy. I’m not sure what you’re refering to by JavaScript console. (sorry) The script runs fine and sensor data is continuously updated. What I’m not getting is the image that was (presumed to be) saved in spiffs. I’ve tried the old IDE as well as 2.xx (what ever the latest is) with the plugin by earlephilhower on github. No luck with any of it.
I can say that using the developers tool box on chrome (f12) I was able to see errors from the browser saying that the resource failed to load.
Since all that I took another approach and converted the image to Base64 and inserted that directly into the index.html in the sketch. That appears to work; I’m still cleaning up the style structure in the html portion. I’ve moved the project over to VScode so I can work on the html as well as the sketch in one location. Slow going with this ole mans brain LOL. I would like to see a version of LittleFS or SPIFFS functionable again. It would keep things much cleaner and more organized.
Thanks to you and Rui for all the hard work!
Hi again.
If the picture is not showing, it’s probably because it didn’t upload to the filesystem. So, it can’t find the picture to display on the web page.
You need to use the old Arduino IDE to upload files or VS Code. Or even the command line.
Regards,
Sara
Hi Sara, thanks again. OK so I did try to upload with the old IDE also, neither worked. If I may I’ll bring you up to date as to how I spent my day today.
So, I have one machine (laptop) running Win10, a desktop running Win11, along with generic ESP8266’s, and D1 mini’s and 3 different programmers. The laptop has both 1.8.16 and 2.2.1 versions of the IDE. For the newer version, there is a plugin that is fairly new on github that supposedly works. I couldn’t get it to talk to any of the ESP’s. It kept throwing connection errors, even though the IDE would upload a sketch. I put that one on the shelf. In VScode, I can’t seem to find a library for the ESP8266 so I shelved that too. When using the old IDE, I used the Littlefs library to upload. It “acted” like it did that, but the results were as stated. I have no idea how to load from command line. Questions I have is this: is there any way to read the flash memory on the ESP8266 to see if anything was uploaded? I tried the test program from one of your earlier projects to demonstrate SPIFFS and substituted Littlefs. That was simply a text file, to be read and printed out through the serial monitor. No luck with that. I’m not sure if the library I’m using is correct or not since the IDE “acts” like things are uploading. Another question: is the retrieval of the files a function of the library? There is always a mention of uploading but never anything about retrieval. That makes me think it is part of the library. Yes,No? Anyway Thanks for your help, I can’t believe I’m the only one with these issues, but I see very little information on it out there. Cheers
Hi Again Sara, May I bring you (and readers) up to date. After much frustration, I decided to uninstall/reinstall the 1.8.16 IDE. After that I reinstalled the LittleFS plugin. Then loaded the sketch from https://randomnerdtutorials.com/display-images-esp32-esp8266-web-server/. Lo and behold it worked. I then replaced the images from that with my .jpg image. It worked! (wow).
I then tried my original sketch. Again the image didn’t show đ Then I opened both said sketches and copied each html element from my old one to the one from the tutorial. Testing between each one was a success. Since I had the HTML portion working (and I don’t know why it worked on one and not the other) I went on to copy/paste the rest of my sketch into the new one, again testing as I went. The end result was it worked. But the original didn’t. The syntax, etc is exactly the same. The only thing I can think of is with the number of changes made in systems,OS’s, disk drives etc. since the original sketch was written there may have been some unseen corruption in that file. I guess I should have started fresh in the first place.
My next goal would be to be able to put the HTML index file, and CSS file into flash as well instead of having it imbedded in the sketch. I couldn’t get that to work in the original sketch. I’m not sure how to pass all 3 components of the webpage from flash (HTML,CSS,image). Is there a tutorial anywhere on that subject you (or readers) know of? Thanks for your guidance/help. Cheers
Hi.
Are you using LittleFS or SPIFFS?
Are you using the image names or paths? For example, image.png or /image.png
We have many web server examples that use HTML, CSS and javascript on separate files on the filesystem.
This is the most basic: https://randomnerdtutorials.com/esp32-web-server-spiffs-spi-flash-file-system/
But, other examples like this:https://randomnerdtutorials.com/esp32-websocket-server-sensor/ also use that approach.
Regards,
Sara
Hi Sara, thanks sooo much for your guidance. So I was able last night to get to a point where I could serve the html index file (with it’s css styling), as well as one out of 3 images.
The data folder contains the index.html, 3 jpg images, a style.css, and a script.js.
I am using LittleFS (version from https://github.com/earlephilhower/arduino-esp8266littlefs-plugin)
I’m using /image.jpg and /script.js
The order in the sketch using “server.on” is first index.html, then style.css, then script.js, then images, then variables resulting from the script. Does the order matter?
I have some time today, hopefully I’ll make some progress. I’m not sure if my errors are in the sketch or the html structure. I should note that when I built the page in an html editor, it all came together in the preview with out the script of course because it wasn’t running the sketch.
Cheers, and thanks again
Hi Sara, Another update. In my limited experience with HTML I’ve always used the statement:
<image src=”image.jpg” alt= “discription of image”
so that was what I used. on images. That didn’t work. Then removed the “alt” attribute, and the images were served to the browser. As for the style.css That was simply a oversight in naming disagreement that I didn’t catch. Once in agreement between documents the style.css loaded and functioned fine. The Script.js however is another story. I have not gotten it to work still.
At first I had similar naming issues like the Style.css. After clearing that up it appeared that the script file was served, but didn’t run. (Results never published to replace the placeholders on the page. Checking with the Chrome developers tools showed that the file had indeed been received…I then imbedded the script into the HTML index file, using the tag. and it works beautifully. I must be missing something here.
Cheers
Hello! thanks for this article!
I donât get the download function after a restart, although I added it to the folders
C:\Users\fos\AppData\Local\Programs\Arduino IDE\tools
C:\Users\fos\OneDrive\Documents\Arduino\tools
If youâre using Arduino IDE 2, this is the tutorial you need to follow: https://randomnerdtutorials.com/arduino-ide-2-install-esp8266-littlefs/
Hi
please help me with this code, what am i doing wrong or missing something, Im pasting ccopy of error messege.
Arduino: 1.8.19 (Windows 10), Board: “Generic ESP8266 Module, 80 MHz, Flash, Legacy (new can return nullptr), All SSL ciphers (most compatible), dtr (aka nodemcu), 26 MHz, 40MHz, DOUT (compatible), 1MB (FS:64KB OTA:~470KB), 2, nonos-sdk 2.2.1+100 (190703), v2 Lower Memory, Disabled, None, Only Sketch, 115200”
In file included from C:\Users\Gurs_PC\Desktop\ESP8266_Gauges\ESP8266_Gauges.ino:15:0:
C:\Users\Gurs_PC\Documents\Arduino\libraries\Adafruit_BME280_Library-master/Adafruit_BME280.h:26:32: fatal error: Adafruit_I2CDevice.h: No such file or directory
#include <Adafruit_I2CDevice.h>
^
compilation terminated.
exit status 1
Error compiling for board Generic ESP8266 Module.
This report would have more information with
“Show verbose output during compilation”
option enabled in File -> Preferences.
Hi.
It seems you need to install this library: Adafruit_I2CDevice.h
Regards,
Sara