Install ESP32 Filesystem Uploader in Arduino IDE

The ESP32 contains a Serial Peripheral Interface Flash File System (SPIFFS). SPIFFS is a lightweight filesystem created for microcontrollers with a flash chip, which are connected by SPI bus, like the ESP32 flash memory. In this article we’re going to show how to easily upload files to the ESP32 filesystem using a plugin for Arduino IDE.

Install ESP32 Filesystem Uploader in Arduino IDE

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

Introducing SPIFFS

SPIFFS lets you access the flash 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. At the time of writing this post, SPIFFS doesn’t support directories, so everything is saved on a flat structure.

Using SPIFFS with the ESP32 board is specially useful to:

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 a separated file and save them on the ESP32 filesystem. Check the following tutorial to learn how to build a web server with files stored on the ESP32 file system:

Installing the Arduino ESP32 Filesystem Uploader

You can create, save and write files to the ESP32 filesystem by writing the code yourself on the 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 ESP32 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 ESP32 add-on for the Arduino IDE. If you don’t, follow one of the following tutorials to install the add-on:

Follow the next steps to install the filesystem uploader:

1) Go to the releases page and click the ESP32FS-1.0.zip file to download.

Download ESP32 SPIFFS Filesystem fs for Arduino IDE

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

Arduino IDE Tools to Install ESP32 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/ESP32FS/tool/esp32fs.jar
Arduino IDE Tools to Install ESP32 SPIFFS Filesystem fs

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

ESP32 Sketch Data Upload Arduino IDE SPIFFS FS Filesystem

Uploading Files using the Filesystem Uploader

To upload files to the ESP32 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.

ESP32 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 ESP32 filesystem. As an example, create a .txt file with some text called test_example.

ESP32 Notepad Test Example File Filesystem fs SPIFFS

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

ESP32 Sketch Data Upload Arduino IDE SPIFFS FS Filesystem

The uploader will overwrite anything you had already saved in the filesystem.

Note: in some ESP32 development boards you need to keep the ESP32 on-board “BOOT” button pressed while it’s uploading the files. When you see the “Connecting …….____……” message, you need to press the ESP32 on-board “BOOT” button.

SPIFFS Image Connecting to ESP32 board

When you see the message “SPIFFS Image Uploaded“, the files were successfully uploaded to the ESP32 filesystem.

SPIFFS Image Uploaded to ESP32 board

Testing the Uploader

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

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

#include "SPIFFS.h"
 
void setup() {
  Serial.begin(115200);
  
  if(!SPIFFS.begin(true)){
    Serial.println("An Error has occurred while mounting SPIFFS");
    return;
  }
  
  File file = SPIFFS.open("/test_example.txt");
  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() {

}

View raw code

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

ESP32 SPIFFS FS Filesystem Example Arduino IDE Serial Monitor

You’ve successfully uploaded files to the ESP32 filesystem using the plugin.

Wrapping Up

Using the filesystem uploader plugin is one of the easiest ways to upload files to the ESP32 filesystem. Check the following project to see how to build a web server using HTML and CSS files stored on the filesystem: ESP32 Web Server using SPIFFS (SPI Flash File System).

For more projects with ESP32, check the following tutorials:

This is an excerpt from our course: Learn ESP32 with Arduino IDE. If you like ESP32 and you want to learn more, we recommend enrolling in Learn ESP32 with Arduino IDE course.



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 »

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!

73 thoughts on “Install ESP32 Filesystem Uploader in Arduino IDE”

  1. You stated that “After uploading, open the Serial Monitor at a baud rate of 115200. Press the ESP32 “ENABLE” button.”

    Just where is this ESP32 “ENABLE” button located?

    My sketch does not show any of the test data from the text file. It does print out “File Content:”. But nothing elese.

    And even when I deliberately rename the file in the sketch to something else, it does not tell me that “Failed to open file for reading” but still displays “File Content:” with nothing else.

    I am using Arduino 1.8.5 on Windows 10

    Reply
  2. Boa tarde!

    Será possível através dos SPIFFS controlar os GPIO do ESP32? Ou seja, eu quero gravar um ficheiro de configuração (formato json) onde indico que pinos desejo ler os dados de sensores do meu ESP32, quando ele arrancar vai ler esse ficheiro.

    Cumprimentos,

    Francisco Pinheiro

    Reply
  3. So far I haven’t been successful uploading additional files.

    SPIFFS.open(“[FilePath]”) always returns true whether or not the file was uploaded.
    SPIFFS.exists(“[FilePath]”) return false whether or not the file was included in the /data directory.

    Specs
    Mac OS 10.14.5
    Arduino IDE 1.8.9
    On an ESP32
    Using Arduino IDE > Tools > Board > ESP32 Dev Module

    Reply
    • Hi Carl.
      I’ve never faced that issue.
      Unfortunately, without further information, it is very difficult to understand what might be wrong.
      If anyone knows a solution for this, please help.
      Regards,
      Sara

      Reply
  4. Hi: I’m trying to install ESP32 filesystem uploader into the Arduino IDE 1.8.5. I have the esp32fs.jar in this path: Macintosh HD⁩ ▸ ⁨Users⁩ ▸ ⁨richardromig⁩ ▸ ⁨Dropbox⁩ ▸ ⁨Arduino IDE 1.8.5⁩ ▸ ⁨Tools⁩ ▸ ⁨ESP32FS⁩ ▸ ⁨tool⁩ but the option “ESP32 Sketch Data Upload“ does not appear in the IDE. I am running MacOS 10.14.6 Any suggestions?

    Reply
    • yes, I copied-pasted the file esp32fs.jar in creating some folders like this : Macintosh HD⁩ ▸ ⁨Utilisateurs⁩ ▸ ⁨MyName ▸ ⁨Documents⁩ ▸ ⁨Arduino⁩ ▸ ⁨tools⁩ ▸ ⁨ESP32FS⁩ ▸ ⁨tool⁩ ▸ esp32fs.jar and the option “ESP32 Sketch Data Upload“ appear in the IDE.

      macOS Mojave 10.14.6

      Reply
  5. Very important for linux users! I create in data folder text file. Then I do same, but I dont see file content (nothing wrong, just dont see characters). Then I try to rename file to like this “test_example.txt”. And it works! In linux, mostly txt file is not txt file.

    Reply
  6. Hi.
    Richard , I had the same problem. But creating a Tools folder under the Sketch folder and placing the ESP32FS⁩ there did the trick.-Not the first time something like this comes up.

    Reply
    • Thanks, I tried all of the other options mentioned and they didn’t work. Yours, however, did work. Many thanks. I’m migrating from Windows to Mac and things are a bit different. I also had to move by library folder into the sketches folder.

      Reply
  7. I had a problem when I installed the ESP32 filesystem uploader in a new tools folder where all my arduino archives are kept. It didn’t install properly.
    However, it worked when I installed the uploader to Local Disk(c:), Program Files(x86), Arduino, tools folder.
    Excellent.
    Just make sure a data folder is in the same folder as your arduino code.

    Reply
  8. For those who had problem when uploading and got error code :

    serial.serialutil.SerialException: could not open port ‘COM3’: WindowsError(5, ‘Access is denied.’)

    Turn your serial monitor or plotter off. I hope it helps…
    Source : Stupid mistake I made.

    Reply
  9. I am having zero luck with this.

    I can upload the SPIFFS file the first time and then thereafter I get:

    [SPIFFS] data : /Users/davidh/Documents/Arduino/spiffs-check/data
    [SPIFFS] start : 2686976
    [SPIFFS] size : 1472
    [SPIFFS] page : 256
    [SPIFFS] block : 4096
    /test_example.txt
    [SPIFFS] upload : /var/folders/n1/59y24n0j2z128fchsgxh1f5w0000gn/T/arduino_build_804785/spiffs-check.spiffs.bin
    [SPIFFS] address: 2686976
    [SPIFFS] port : /dev/cu.SLAB_USBtoUART
    [SPIFFS] speed : 921600
    [SPIFFS] mode : dio
    [SPIFFS] freq : 80m

    esptool.py v2.6
    Serial port /dev/cu.SLAB_USBtoUART
    Traceback (most recent call last):
    File “esptool.py”, line 2959, in
    File “esptool.py”, line 2952, in _main
    File “esptool.py”, line 2652, in main
    File “esptool.py”, line 222, in init
    File “serial/init.py”, line 88, in serial_for_url
    File “serial/serialposix.py”, line 268, in open
    serial.serialutil.SerialException: [Errno 16] could not open port /dev/cu.SLAB_USBtoUART: [Errno 16] Resource busy: ‘/dev/cu.SLAB_USBtoUART’
    Failed to execute script esptool
    SPIFFS Upload failed!

    If I restart the Arduino application it uploads. However running the SPIFFS read test program always comes up with failed to open file for reading.

    So issues with upload and with reading.

    Reply
  10. I am not having much luck with the web servers using the SPIFF. I am using Arduino V1.8.13. When I try to include the .zip library ESP32FS-1.0 I always get the error message: “TTGO LoRa32-OLED V1, 80MHz, 921600, None”
    “Specified folder/zip file does not contain a valid library”

    I am wondering if the LoraESP32 board supports ESP32FS.
    Thanks

    Reply
    • Hi Brian.
      Where are you trying to include the filesystem uploader?
      It shouldn’t be in the project folder.
      The data folder should be in the project folder.
      You’re probably not installing the uploader plugin properly.
      Regards,
      Sara

      Reply
    • 1.) I download ESP32FS-1.0.zip
      2.) In Arduino IDE, I go to: Sketch -> Include Library-> Add .zip Library
      3.) I choose ESP32FS1.0.zip from my download folder.
      4.) I get the following error message at the bottom of the IDE:

      “Specified folder/zip file does not contain a valid library” with an orange background.

      The newer versions of Arduino IDE do not have a Tool folder like the previous versions.
      Should I maybe just unzip the ESP32FS-1.0.zip outside of the Arduino IDE and place the .jar file in a Tool folder that I create myself?
      Many thanks for your help!

      Reply
  11. Hello Sara,
    Thank you very much for this tutorial and it worked well for me, but when I opened the serial monitor, after the sketch had been down loaded, it was blank. However, I realized that the text had been and gone before I opened the monitor and I just pressed the reset button on the ESP32 board and up came the text as you specified. I wonder is this would be of help to the gentleman who seemed to have similar problems.

    I was so pleased that this worked for me as yesterday evening I had been trying for hours to try and get LittleFS working without success and I spotted your tutorial, like a life belt to a drowning man.
    Kindest regards
    Adrian

    Reply
  12. Hi Rui and Sara,

    A slight word of warning/note: The uploader will overwrite anything you had already saved in the filesystem. For me, not a big deal since it was just some test files for an ESP32-based shell/file editor I’ve been working on. But in a production environment where I might be saving config files and runtime data, this would be an issue.

    You might wish to note this in the text of the tutorial (unless I missed it!!).

    Steve

    Reply
  13. For those who struggling on Mac.
    Make a folder, “tools” inside Arduino directory.
    Then, move downloaded folder to “tools” folder
    Finally, you should change the the name of the folder from “ESP32FS 2” to “ESP32Fs”.
    Now, you may find “ESP32 Sketch Data Upload” at the tools bar.

    Reply
  14. Hi Rui et al,
    Great project!
    I’m quite new in the field, please help me out:
    I’m getting the “expected unqualified-id before ‘<‘ token
    ” error while trying to compile the code, line 23 ().
    Where should I dig?
    Regards,
    Th.

    Reply
    • Hi.
      that is a syntax error.
      Double-check that you have copied the complete code and that you haven’t inserted any character by mistake.
      Regards,
      Sara

      Reply
  15. Thank you. I looked at many sites for instructions for installing “Sketch Data Upload” plugins. This is the only site that gave the correct folder location for Windows 10. Thanks again. You are always the best source for information about ESP devices.

    Reply
  16. Hi Rui and Sara,
    Very good your tutorial on ElegantOTA library. Congratulations!
    I wonder if there is any way or library to do a remote update, that is, I am in one place and ESP32 is in another.

    Reply
  17. I have a SPIFFS based webserver (based in your post on that).
    I want to and a settings file to store wifi crefentials etc. But if I do that next time I upload the SPIFFS image I loose all settings stored on my settings file. Is there a way to keep the settings?

    Reply
  18. I was able to do this to get SPIFFS working, but I was hoping that it could show how to log a temperature and light (LDR) reading or some couple of sensors.

    if you are going to do a follow-up, the next step would be data logging to SPIFFS

    Reply
  19. I’m stuck ar this step:

    “3) Unzip the downloaded .zip folder to the Tools folder. You should have a similar folder structure:
    /Arduino-/tools/ESP32FS/tool/esp32fs.jar”

    There’s no “tools” folder in Arduino for Mac.
    Where should it be placed then?

    Reply
  20. Hi,
    I have installed Arduino 1.8.15. Then installed the ESP32FS downloaded from https://github.com/me-no-dev/arduino-esp32fs-plugin/releases/ website and placed under C:\Program Files (x86)\Arduino\tools folder. After that I was able to see “ESP32 Sketch Data Upload” in my tools menu of IDE. But when I click there I get “SPIFFS Error: esptool not found!”

    My sketch folder is “C:\Users\jinda\OneDrive\Documents\Arduino\hardware\heltec\IRserver3” As I was reading the comments I tried putting the ESP32FS under the tools folder under IRserver3 but it still didn’t work. Any help please?

    Reply
  21. I have Arduino IDE 1.8.16 from the Windows Store, not the version from Arduino website. I cannot locate the “Tools” folder anywhere to copy the plugin into. I am running latest update of Windows 10.

    Have checked /AppData/Local (no Arduino folders at all here), same for AppData/Roaming

    Have checked the Sketchbook location and the ArduinoData folder that sits next to that. Nowhere do I have a Tools folder!

    Has anyone else encountered this or have a solution as to where to copy the plugin for this version of the Arduino IDE?

    Reply
  22. Perfect. Reinstalled from Arduino website and now I can have the tools folder, and the Data Uploader appears in the Tools menu in the IDE.

    Unable to actually do the upload however, as I get “SPIFFS Error: serial port not defined!” popping up as an error. I am using an AiThinker ESP32Cam board, which of course does not have a direct USB connection, and I think this might be the cause of the issue.

    Have you found a way to upload to SPIFFS on one of these ESP32Cam boards?

    I’ve never been able to get serial monitor to work with one of these ESP32Cam boards (but have with other ESP32 boards that have direct USB), so I’m wondering if there is a clever way to get Arduino IDE to recognise serial connection that would also enable upload to SPIFFS on an ESP32Cam?

    Reply
    • Progress – managed to get SPIFFS upload to start but, it only gets as far as “Connecting…..___…..” then “A fatal error occured: Failed to connect to ESP32: Timed out waiting for packet header” then “SPIFFS Upload Failed”

      I discovered that other ESP32 boards have way more options in the tools menu than the AIThinker ESP32Cam has (like partition scheme for example). So as a test, I swapped from ESP32Cam to Wrover, then back again, and for some reason that allowed the serial port error to go away.

      Reply
      • Hi.
        When you see the dots on the debugging window ….___….____ press the on-board RST button and it will upload the spiffs image.
        To be able to see the Serial Monitor, you must disconnect GPIO 0 from GND after uploading the code.
        Regards,
        Sara

        Reply
        • Thanks Sara – that has been an awesome help. Fixed two issues at once! When my project is complete I’ll send through the details. Have really enjoyed the tutorials, e-books and courses that you and Rui have made available.

          Reply
  23. Hi,
    Thank you for the tutorial. I has been many learning from your tutorial.
    I have problem related ESP32 Sketch Data Upload plugin. Is it available for ubuntu 20.04 arduino ide?
    Thank you very much.

    Hendry

    Reply
  24. Hi Sara

    Thanks a lot for those tutos and help you provide for all of us, you website is a reference to me before starting anything with ESP chip.

    I am under Win10 and Arduino 1.8.13

    I follow your instructions and createa tools folder before uncompressing the uploader and it works but:
    Now I am trying to upload on a ESP32-C3 dev module then got error message :

    esptool.py v3.1
    Serial port COM11
    Connecting….

    A fatal error occurred: This chip is ESP32-C3 not ESP32. Wrong –chip argument?
    SPIFFS Upload failed!

    Of course I check my setup to confirm I select the right chip in tools board selection

    Do you know if there is an other way to specify chip argument ?

    Reply

Leave a Reply to Adrian Cancel reply

Download our Free eBooks and Resources

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