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

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 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:

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  

#include "FS.h"
void setup() {
    Serial.println("An Error has occurred while mounting SPIFFS");
  File file ="/test_example.txt", "r");
    Serial.println("Failed to open file for reading");
  Serial.println("File Content:");
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

Build Web Server projects with the ESP32 and ESP8266 boards to control outputs and monitor sensors remotely. Learn HTML, CSS, JavaScript and client-server communication protocols DOWNLOAD »

Build Web Server projects with the ESP32 and ESP8266 boards to control outputs and monitor sensors remotely. Learn HTML, CSS, JavaScript and client-server communication protocols DOWNLOAD »

Enjoyed this project? Stay updated by subscribing our newsletter!

36 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

    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…

  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?

  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\

    Python was not found but can be installed from the Microsoft Store: 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.

    • 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

  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

  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

  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

  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

  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.

  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?

      • 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?

  10. Hi Sara-Rui,

    I have installed in the following directory on the Mac:

    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
    [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/

    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}]]

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

    Any solution to this problem?

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

  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


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.