Learn how to upload files to the ESP32 board filesystem (SPIFFS) using VS Code with the PlatformIO IDE extension (quick and easy). Using the filesystem with the ESP32 can be useful to save HTML, CSS and JavaScript files to build a web server instead of having to write everything inside the Arduino sketch.

If you’re using Arduino IDE follow this tutorial instead:Install ESP32 Filesystem Uploader in Arduino IDE.

Introducing SPIFFS

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.

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. SPIFFS doesn’t support directories, so everything is saved on a flat structure.

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

Upload Files to ESP32 SPIFFS

The files you want to upload to the ESP32 filesystem should be placed in a folder calleddata under the project folder. For you to understand how everything works, we’ll upload a.txt file with some random text. You can upload any other file type.

If you’re not familiar with VS Code + PlatformIO, follow the next tutorial first:

• Getting Started with VS Code and PlatformIO IDE for ESP32 and ESP8266

Creating a data Folder

Create a folder calleddatainside your project folder. This can be done on VS Code.
With your mouse, select the project folder you’re working on. Click on theNew Folder icon to create a new folder.

This new folder must be calleddata, otherwise, it won’t work.

Then, select the newly createddatafolder and create the files you want to upload by clicking on theNew File icon. In this example, we’ll create a file calledtext.txt. You can create and upload any other file types like.html,.css or.js files, for example.

Write some random text inside that.txt file.

Thedatafolder should be under the project folder and the files you want to upload should be inside thedatafolder. Otherwise, it won’t work.

Uploading Filesystem Image

After creating and saving the file or files you want to upload under thedata folder, follow the next steps:

1. Click the PIO icon at the left side bar. The project tasks should open.
2. Selectenv:esp32doit-devkit-v1 (it may be slightly different depending on the board you’re using).
3. Expand thePlatformmenu.
4. SelectBuild Filesystem Image.
5. Finally, clickUpload Filesystem Image.

Important: to upload the filesystem image successfully you must close all serial
connections (Serial Monitor) with your board.

After a while, you should get a success message.

Troubleshooting

Here’s some common mistakes:

Could not open port “COMX” Access is denied.

This error means that you have a serial connection opened with your board in VS Code or in any other program. Close any program that might be using the board serial port, and make sure you close all serial connections in VS Code (click on the recycle bin icon on the terminal console).

Timed out waiting for packet header error

If you start seeing a lot of dots on the debugging window and the filesystem image fails to upload, you need to press the on-board boot button once you start seeing the dots.

To solve this issue permanently, read the following article:

• [SOLVED] Failed to connect to ESP32: Timed out waiting for packet header

Testing

Now, let’s just check if the file was actually saved into the ESP32 filesystem. Copy the following code to themain.cpp file and upload it to your board.

/*********  Rui Santos  Complete project details at https://RandomNerdTutorials.com/esp32-vs-code-platformio-spiffs/  *********/#include <Arduino.h>#include "SPIFFS.h" void setup() {  Serial.begin(9600);    if(!SPIFFS.begin(true)){    Serial.println("An Error has occurred while mounting SPIFFS");    return;  }    File file = SPIFFS.open("/text.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

You may need to change the following line depending on the name of your file.

File file = SPIFFS.open("/text.txt");

Open the Serial Monitor and it should print the content of your file.

You’ve successfully uploaded files to the ESP32 filesystem (SPIFFS) using VS Code + PlatformIO.

Wrapping Up

With this tutorial you’ve learned how to upload files to the ESP32 filesystem (SPIFFS) using VS Code + PlatformIO. It is quick and easy.

This can be specially useful to upload HTML, CSS and JavaScript files to build web server projects with the ESP32 boards.

We have a similar tutorial for the ESP8266 NodeMCU:ESP8266 NodeMCU with VS Code and PlatformIO: Upload Files to Filesystem (LittleFS)

Learn more about the ESP32 with our resources:

• Learn ESP32 with Arduino IDE (eBook + video course)
• MicroPython Programming with Arduino IDE (eBook)
• More ESP32 Tutorials and Projects…

20 thoughts on “ESP32 with VS Code and PlatformIO: Upload Files to Filesystem (SPIFFS)”

1. I did the tutorial for ESP8266, using the LittleFS filesystem, but this one donn’t menton it. Why? The littleFS is also available for the ESP32?

   Reply

2. I have done this tutorial sucessfully with my ESP32 bord. It was very informative, thank you!
   One question remain, since I read in the linked tutorial “ESP8266 NodeMCU with VS Code and PlatformIO: Upload Files to Filesystem (LittleFS)” that “SPIFFS is currently deprecated and may be removed in future releases of the core.”:
   Is this also true for the ESP32? Should I rather use LittleFS (in case it works on ESP32, not tried yet) than the SPIFFS approch presented in this tutorial?

   Reply

   • For now, SPIFFS works just fine for the ESP32.

     Reply

     • ERROR: ‘File’ was not declared in this scope

       SOLUTION: Just added SPIFFS.h after the first line, otherwise not working ,

       #include <FS.h> //this needs to be first, or it all crashes and burns…
       #include “SPIFFS.h”

       Reply

       • Thanks Mate ! you made my day (and my night 😉
         but why ?? it doen t make sense to me !

         Reply

3. Nice tutorial , one thing i am missing is what happens to other files that are already on the SPIFFS will those be removed or will the new files just added to it?

   Reply

4. Thanks for this tutorial, once more a great one. Is it possible to load small mp3 files to SPIFFS and then play them by the name?

   Reply

   • Hi.
     Yes, you can upload any file to SPIFFS as long as it fits in size.
     Yes, you can play the files using an MP3 module with the ESP32. We don’t have any projects about audio at the moment.
     Regards,
     Sara

     Reply

5. Hi Sara,
   I was wondering if it’s possible to select the “target” destination where to upload the files.
   As i would like to connect an extra (external) SPI flash (MOSI-MISO-SCK-CS), i would like to know if it’s possible to upload files on it, and not in the internal falsh…
   Makes sense..?
   Thanks a lot

   Reply

6. Hi Sara ,

   I’ll use my build web server tutorial and have a problem with SPIFFS and the ESP32.

   Application 1.1 – Hello World Web Server is working fine
   Application 1.2 – Hello World Web Server with SPIFFS is not working under platformio.
   After build I get a failure . I’ll think the different point ist the SPIFFS .
   I tried this application here to test the readout of the SPIFFS ,without any changes to to your application and after compiling the read out is File Content: no text is shown.
   The folder and file structure is the same as you listed here,
   I use the az delivery devkit v4 version which should be OK because 1.1 is running
   Depending on this negativ result I think it is the same issue for the 1.2 application.

   To go forward with my training I’ll need in the next application a running SPIFFS.

   Can you ple3ase give me a hint what may be is wrong at my test ?

   Thanks Axel

   Reply

   • Hi.
     If you are one of our customers, I recommend posting your issue on the RNTLAB forum:https://rntlab.com/forum/
     I always answer the forum first.
     Please provide information about the error you get when you say you get a failure.
     Regards,
     Sara

     Reply

7. Please explain how to change the SPIFFs partition in Platformio.

   Reply

8. Arduino IDE 2.0 does not support SPIFFS uploading files.
   this project solves that problem
   github.com/palmerr23/ESP32-OTA-and-File-Manager

   Reply

   • Great.
     Thanks for sharing.
     Regards,
     Sara

     Reply

9. Hi,
   I am trying to upload spiffs from visual Studio Code.

   Working through the instructions I cant see how to install the spiffs file system uploader in VSC.

   When I click on build filesystem image in VSC I get the following error:
   Building SPIFFS image from ‘data’ directory to .pio/build/esp32dev/spiffs.bin

   sh: 1: mkspiffs_espressif32_arduino: not found
   *** [.pio/build/esp32dev/spiffs.bin] Error 127

   do I need to install it within the Arduino IDE first?

   Steve

   Reply

   • Typical, as soon as I post a question 10 minutes later I solve it!

     I am using VSC on a PI4 running the 64 bit Raspberry PI OS.

     I followed this post
     https://community.platformio.org/t/cant-build-filesystem-image-sh-1-mkspiffs-espressif32-arduino-not-found-error-127/19295/3

     and re-built the file and it works a treat!

     Steve

     Reply

10. My question is more related to PlatformIO. I want to do the Filesystem Upload, but there is no Build Filesystem Image or Upload Filesystem Image under my PlatformIO menu.

    Reply

    • Hi.
      Did you click on the little alien icon to show the project tasks?
      Regards,
      Sara

      Reply

11. Hi, I was able to upload successfully my files but the Wifi of my esp8266 01 stop working, no Ap and no station connection.
    Could any one help please?

    Reply

12. Thank you, worked out-of-the-box.

    Reply