Use ESP32 with VS Code & Platformio IDE to Upload Files to Filesystem (SPIFFS)

Learn how to Use ESP32 with VS Code & Platformio to Upload Files to Filesystem (SPIFFS). Instead of needing to write everything within the Arduino sketch, it may be useful to leverage the filesystem with the ESP32 to save HTML, CSS, and JavaScript files to create a web server.

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

Introducing SPIFFS

The Serial Peripheral Interface Flash File System (SPIFFS) is built into the ESP32. For microcontrollers with flash memory chips connected through the SPI bus, like the ESP32 flash memory, SPIFFS is a lightweight filesystem.

Although SPIFFS is simpler and has fewer features than a normal filesystem on your computer, it still allows you to access flash memory. You can open, shut, read, write, and delete files. Since directories are not supported by SPIFFS, everything is saved as a flat structure.

Using SPIFFS with the ESP32 board 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.

Upload Files to ESP32 SPIFFS

Under the project folder, under the data folder, put the files you want to upload to the ESP32 filesystem. We'll upload a .txt file with some random text to help you understand how everything works. Any other file type is acceptable for upload.

Creating a data Folder

Inside the folder for your project, create a folder called data. VS Code can be used for this. Select the project folder that you are working on with your mouse. To create a new folder, click the “New Folder” button.

Otherwise, it won't work. This new folder must be called data.

Create a data folder VS Code PlatformIO ESP32

Select the files you wish to upload by clicking the New File icon in the newly formed data folder. We'll create a file called “text.txt” for this example. Any other file type, like .html, .css, or .js files, may be created and uploaded.

Create files under data folder VS Code with PlatformIO ESP32

Write some random text inside that “.txt” file.

The data folder should be within the project folder, and the files you wish to upload should be inside the data folder. It will not work otherwise.

Create text file VS Code PlatformIO ESP32

Uploading Filesystem Image

Follow the next steps after creating and saving the file or files you want to upload to the data folder:

  1. Click the PIO icon in the left sidebar. The project tasks should be open.
  2. Select env:esp32doit-devkit-v1 (it may be slightly different depending on the board you’re using).
  3. Expand the Platform menu.
  4. Select Build Filesystem Image.
  5. Finally, click Upload Filesystem Image.
Upload Filesystem Image VS Code PlatformIO ESP32

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.

Upload filesystem image ESP32 VS Code PlatformIO success message


Here are some common mistakes:

Could not open port “COMX” Access is denied.

Upload filesystem image ESP32 VS Code PlatformIO Access Denied Error

This issue signifies that in VS Code or any other program, a serial connection has been opened with your board. Make sure to close all serial connections in Visual Studio Code (click the recycle bin icon on the terminal console) and terminate any programs that could be using the board serial port.

VS Code PlatformIO Close Terminal Window

Timed out waiting for packet header error

Timed out waiting for packet header error VS Code PlatformIO

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

To solve this issue permanently, read the following article:


Check to see if the file was really saved to the ESP32 filesystem now. In the main.cpp file, paste the following code, then upload it to your board:

  Complete project details at  

#include <Arduino.h>
#include "SPIFFS.h"
void setup() {
    Serial.println("An Error has occurred while mounting SPIFFS");
  File file ="/text.txt");
    Serial.println("Failed to open file for reading");
  Serial.println("File Content:");
void loop() {


The following line may need to be changed depending on the name of your file:

File file ="/text.txt");

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

Reading File Content SPIFFS ESP32 VS Code PlatformIO

You’ve successfully used ESP32 with VS Code & Platformio to upload files to Filesystem (SPIFFS).


In this tutorial, you've learned how to upload files to the ESP32 filesystem (SPIFFS) using VS Code & PlatformIO. It is quick and simple.

This can be especially useful for uploading HTML, CSS, and JavaScript files to develop web server projects with the ESP32 boards.

If you like ESP32, you may also like:

We hope you find this tutorial useful. Thanks for reading.

Oh hi there It’s nice to meet you.

Sign up to receive awesome content in your inbox, every month.

We don’t spam! Read our privacy policy for more info.

Leave a Reply

Your email address will not be published. Required fields are marked *

Developing IoT Projects with ESP32

Automate your home or business with inexpensive Wi-Fi devices