Install ESP8266 Filesystem Uploader in Arduino IDE

The ESP8266 contains a Serial Peripheral Interface Flash File System (SPIFFS). SPIFFS is a lightweight filesystem created for microcontrollers with a flash chip. This article shows how to easily upload files to the ESP8266 filesystem using a plugin for Arduino IDE.

Install ESP8266 Filesystem Uploader in Arduino IDE

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. Follow this tutorial instead: Install ESP8266 NodeMCU LittleFS Filesystem Uploader in Arduino IDE.

Note: if you have an ESP32 board, read Install ESP32 Filesystem Uploader in Arduino IDE.

Introducing SPIFFS

SPIFFS lets you access the flash chip memory like you would do in a normal filesystem in your computer, but simpler and more limited. You can read, write, close, and delete files. SPIFFS doesn’t support directories, so everything is saved on a flat structure.

Using SPIFFS with the ESP8266 board is specially 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 and CSS files to build a web server;
  • Save images, figures and icons;
  • And much more.

In most of our web server projects, we’ve written the HTML code for the web server as a String directly on the Arduino sketch. With SPIFFS, you can write the HTML and CSS in separated files and save them on the ESP8266 filesystem.

Installing the Arduino ESP8266 Filesystem Uploader

You can create, save and write files to the ESP8266 filesystem by writing the code yourself in Arduino IDE. This is not very useful, because you’d have to type the content of your files in the Arduino sketch.

Fortunately, there is a plugin for the Arduino IDE that allows you to upload files directly to the ESP8266 filesystem from a folder in your computer. This makes it really easy and simple to work with files. Let’s install it.

First, make sure you have the latest Arduino IDE installed, and you have the ESP8266 add-on for the Arduino IDE. If you don’t, follow the next tutorial to install the add-on:

Follow the next steps to install the filesystem uploader:

1) Go to the releases page and click the ESP8266FS-X.zip file to download.

Download ESP8266 SPIFFS Filesystem fs for Arduino IDE

2) Go to the Arduino IDE directory, and open the Tools folder.

Arduino IDE Tools to Install ESP8266 SPIFFS Filesystem fs

3) Unzip the downloaded .zip folder to the Tools folder. You should have a similar folder structure:

<home_dir>/Arduino-<version>/tools/ESP8266FS/tool/esp8266fs.jar
Arduino IDE Tools to Install ESP8266 SPIFFS Filesystem fs

4) 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 Sketch Data Upload“.

ESP8266 Sketch Data Upload Arduino IDE SPIFFS FS Filesystem

Uploading Files 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.

Arduino IDE Show Sketch folder to create data folder

3) Inside that folder, create a new folder called data.

ESP8266 Arduino Sketch Example File Filesystem fs SPIFFS

4) Inside the data folder is where you should put the files you want to be saved into the ESP8266 filesystem. As an example, create a .txt file with some text called test_example.

ESP8266 Notepad Test Example File Filesystem fs SPIFFS

5) In the Arduino IDE, in the Tools menu, select the desired SPIFFS size (this will depend on the size of your files)

ESP8266 Select SPIFFS FS Filesystem size in Tools menu using Arduino IDE

6) Then, to upload the files, in the Arduino IDE, you just need to go to Tools > ESP8266 Sketch Data Upload.

ESP8266 Sketch Data Upload Arduino IDE SPIFFS FS Filesystem

You should get a similar message on the debugging window. The files were successfully uploaded to the ESP8266 filesystem.

SPIFFS Image Connecting to ESP8266 board

Testing the Uploader

Now, let’s just check if the file was actually saved into the ESP8266 filesystem. Simply upload the following code to your ESP8266 board.

/*********
  Rui Santos
  Complete project details at https://RandomNerdTutorials.com  
*********/

#include "FS.h"
 
void setup() {
  Serial.begin(115200);
  
  if(!SPIFFS.begin()){
    Serial.println("An Error has occurred while mounting SPIFFS");
    return;
  }
  
  File file = SPIFFS.open("/test_example.txt", "r");
  if(!file){
    Serial.println("Failed to open file for reading");
    return;
  }
  
  Serial.println();
  Serial.println("File Content:");
  while(file.available()){
    Serial.write(file.read());
  }
  file.close();
}
 
void loop() {

}

View raw code

After uploading, open the Serial Monitor at a baud rate of 115200. Press the ESP8266 “RST” button. It should print the content of your .txt file on the Serial Monitor.

ESP8266 SPIFFS FS Filesystem Example Arduino IDE 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. You can save HTML and CSS 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. The example is for the ESP32, but it should be compatible with the ESP8266 with small changes on the code.

If you like the ESP8266, you may like the following resources:

Thanks for reading



Learn how to build a home automation system and we’ll cover the following main subjects: Node-RED, Node-RED Dashboard, Raspberry Pi, ESP32, ESP8266, MQTT, and InfluxDB database DOWNLOAD »
Learn how to build a home automation system and we’ll cover the following main subjects: Node-RED, Node-RED Dashboard, Raspberry Pi, ESP32, ESP8266, MQTT, and InfluxDB database DOWNLOAD »

Recommended Resources

Build a Home Automation System from Scratch » With Raspberry Pi, ESP8266, Arduino, and Node-RED.

Home Automation using ESP8266 eBook and video course » Build IoT and home automation projects.

Arduino Step-by-Step Projects » Build 25 Arduino projects with our course, even with no prior experience!

What to Read Next…


Enjoyed this project? Stay updated by subscribing our newsletter!

49 thoughts on “Install ESP8266 Filesystem Uploader in Arduino IDE”

  1. Hello Sara,

    Target: Sparkfun ESP8255 Thing,
    Empty sketch => test.ino
    Data: test.txt (in dir data) => Dit is een test…
    IDE: Arduino 1.8.10
    ESP8266FS-0.4.0

    esptool write_flash: error: argument : Must be pairs of an address and the binary filename to write there

    Can you help me?
    Thanks and regards…

    Reply
  2. I don’t see a “programs” folder under documents. Using Windows 10
    I do see this: C:\Program Files (x86)\Arduino\tools, should I decompress to there?

    Reply
  3. I keep getting an error about Python not being installed:

    [SPIFFS] python : python3.exe
    [SPIFFS] uploader : C:\Users\Brian Kenney\AppData\Local\Arduino15\packages\esp8266\hardware\esp8266\2.5.2\tools\upload.py

    Python was not found but can be installed from the Microsoft Store: https://go.microsoft.com/fwlink?linkID=2082640SPIFFS Upload failed!

    I just installed Python for that reason, even though I wasn’t aware that I needed it. Do I need Python? Anyway, it’s looking in a different place than you I believe.

    Reply
    • i had the Pythgon error aswell.
      Use ESP8266FS version 0.5.0, together with the ESP8266 version 2.60 board add-on. All older or newer version combinations didn’t work for me aswell. like Jeroen mentioned

      Reply
  4. Excellent tuto! I’m learning new stuff every day.
    I’m working on a project where I have to send data of a sensor to a server through FTP once a day. Then, data are processed by a php script, which add it to a database and display it into a webpage.
    First, I was thinking using a Mega2560 with a ESP01, but the more I read your tutorials, the more I think I’m going in the wrong direction.
    1. Do you think an esp8266-NodeMCU would be enough for this kind of project (without the Mega2560)?
    2. Can you upload files on a ESP-01, similarly as the NodeMCU?
    3. Can you upload files (including the arduino) from anywhere if you need let’s say to change 1 parameter in your file, or do you have to be next to it?
    4. Have you ever work on such a project?

    Thank you so much in advance for your help

    Reply
  5. “But I managed by using ESP8266FS version 0.5.0, together with the ESP8266 version 2.60 board add-on. All older or newer version combinations didn’t work for me.”

    Thank you, i just had the same Problem

    Reply
  6. Hey Rui&Sara,
    I just updated the IDE in the middle of a project TO 1.8.12 (Yeah I know, dumb). When I went to upload to spiffs, I found the menu didn’t have the necessary item. Then my old brain remembered it had to be installed, BUT, when I wen’t to Iger’s github I see there is an update that is designed to support Python 3.0. In addition following your instructions for adding the feature, the file structure doesn’t add up. I seem to remember a change in that around IDE 1.18.10 or there abouts. So now I’m not sure how to install it. Any help would be greatly appreciated. Thanks

    Reply
  7. Hello everybody,

    I did everything as described here. However, I do not see the SPIFFS size in the tool menu but still the FS OTA as flash size.
    Does anyone have a solution for me?

    Regards Michael

    Reply
  8. Thanks a lot for the tutorial!

    Just a small tip. I spent some hours unable to make the Sketch Data Upload.
    I was getting an error saying “resource busy”.

    Eventually, I found out that while doing the Sketch Data Upload, I must have the Serial Monitor closed.

    Now it’s working.

    Reply
  9. Hi,
    When I use ‘ESP8266 Sketch Upload’ I get a message that ‘SPIFFS Image Uploaded’. But it doesn’t actually upload. The previously uploaded program continues to run. What should I do?

    Reply
      • I tried erasing it. I tried all combinations of tool version 4.0 and 5.0 and board version 2.60 and 2.74 with restarting in between. At best I get ‘SPIFFS Image Uploaded’ but it doesn’t actually upload. Any ideas?

        Reply
        • I get the same problem too. It says SPIFF image uploaded, but I cannot read the file after uploading. I am not evens sure that the file is there or not. Sam please help me out if you had found the solution.

          Reply
      • Hello Sara, Day one for me using an ESP8266. I installed the file system uploader and was able to upload a one line test file and I see its content using your sketch to read and serial.print the contents. Now I need to lean how to delete files no longer needed to free up space. I have been googling for it and not yet found how to do it. Can you tell me how you do that?
        Thank you for your time, help and all the great information you provide.

        Reply
  10. Hi Sara-Rui,

    I have installed ESP8266LittleFS-2.5.1.zip in the following directory on the Mac:
    /Users/carles/Documents/Arduino/tools/ESP8266LittleFS/tool/esp8266littlefs.jar.

    I have the following option in the tool menu:
    ESP8266 LittleFS Data Ulpoad

    When I upload the document I get the following error:
    Arduino:1.8.13 (Mac OS X), Tarjeta:”NodeMCU 1.0 (ESP-12E Module), 80 MHz, Flash, Legacy (new can return nullptr), All SSL ciphers (most compatible), 4MB (FS:1MB OTA:~1019KB), 2, v2 Lower Memory, Disabled, None, Only Sketch, 921600″

    [LittleFS] data : /var/folders/w6/rbt_v68j0xj28wrd4d7pmm6w0000gn/T/untitled509538315.tmp/sketch_jan23a/data
    [LittleFS] size : 1000
    [LittleFS] page : 256
    [LittleFS] block : 8192
    /text.txt
    [LittleFS] upload : /var/folders/w6/rbt_v68j0xj28wrd4d7pmm6w0000gn/T/arduino_build_243359/sketch_jan23a.mklittlefs.bin
    [LittleFS] address : 0x300000
    [LittleFS] reset : –before default_reset –after hard_reset
    [LittleFS] port : /dev/cu.SLAB_USBtoUART
    [LittleFS] speed : 921600
    [SPIFFS] python : python
    [SPIFFS] uploader : /Users/carles/Library/Arduino15/packages/esp8266/hardware/esp8266/2.7.4/tools/upload.py

    usage: esptool [-h] [–chip {auto,esp8266,esp32}] [–port PORT] [–baud BAUD]
    [–before {default_reset,no_reset,no_reset_no_sync}]
    [–after {hard_reset,soft_reset,no_reset}] [–no-stub]
    [–trace] [–override-vddsdio [{1.8V,1.9V,OFF}]]
    {load_ram,dump_mem,read_mem,write_mem,write_flash,run,image_info,make_image,elf2image,read_mac,chip_id,flash_id,read_flash_status,write_flash_status,read_flash,verify_flash,erase_flash,erase_region,version}

    esptool: error: unrecognized arguments: –end
    LittleFS Upload failed!

    Any solution to this problem?

    Reply
    • Also esp8266fs.To insert jar, you can unpack the .zip file and place the ESP8266FS folder inside C:\Program Files (x86)\Arduino\tools.

      Reply
  11. SPIFFS has been downgraded/not used (IDE 1.8.15). Use LittleFS instead (#include LittleFS.h> and change all ocurrences of SPIFFS to LittleFS

    Reply
  12. Hi I’m Ger from the Netherlands with a question: I’m working on the project and it’s a nice learning project, but why do I still have to load many libraries and is it not possible to do this in one go. For example, I am talking about avr/io.h, avr/interrupt.h,
    avr/power.h, avr/pgmspace.h, util/twi.h, and more.

    Thanks for an answer, greetings Ger

    Reply
    • Hi.
      I’m sorry, but I didn’t understand your question.
      What project are you currently running and what issue are you having?
      Regards,
      Sara

      Reply
      • Hi Sara, my apologies for the unclear response. It is about the project “ESP8266 MPU6050 Web Server Accelerometer and Gyroscope Dashboard with 3D Animation (SSE Events)”. As I said a nice learning project for many of us. I myself work with RPI and Python and wanted to shift my mind to Arduino. That works nicely but is a bit slower, but nice projects. My question about the project is that I have the web server running but the html, json, css won’t work. Now I first uploaded files to arduino with SPIFFS because I thought the ESP32 was equal to the ESP8266 but it turned out not to be. Now in the file I use #include <LittleFS.h>, should I upload with LittleFS as well?

        I hope you can give me some explanation as to why I am getting a blank webpage from the web server.

        many thanks and greetings
        Ger

        Reply
      • Hi Sara, I have now uploaded with LittleFS and found a bug in the html script when calling the https://cdnjs in lines 16 and 51. It works now but is very slow. If I build a refresh in the html it works but in between the 3d jumps to 0.

        Do you know a solution for this? I may be asking a lot, but Arduino C+ is still unknown to me.

        thanks in advance,
        Ger

        Reply
  13. I did everything as described here. However, I do not see the SPIFFS size in the tool menu but still the FS OTA as flash size.
    Does anyone have a solution for me?

    Same problem…

    Reply
  14. I’ve attempted another of your tutorials using what I now know is an ESP8266EX – I uploaded the text file using the ESP8266 uploader…then it gives another code to upload but I’m unsure where or with what it just says upload. Well every way I’ve tried has lead in the file not being able to read the text file. I’ve bought chip after chip and still getting the same issues. PLEASE HELP ME.

    Reply

Leave a Comment

Download Our Free eBooks and Resources

Get instant access to our FREE eBooks, Resources, and Exclusive Electronics Projects by entering your email address below.