ESP32 with VS Code and PlatformIO: Upload Files to Filesystem (SPIFFS)

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 called
data
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 called
data
inside your project folder. This can be done on VS Code.
With your mouse, select the project folder you’re working on. Click on the
New Folder
icon to create a new folder.
This new folder must be called
data
, otherwise, it won’t work.
Then, select the newly created
data
folder and create the files you want to upload by clicking on the
New File
icon. In this example, we’ll create a file called
text.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.
The
data
folder should be under the project folder and the files you want to upload should be inside the
data
folder. Otherwise, it won’t work.
Uploading Filesystem Image
After creating and saving the file or files you want to upload under the
data
folder, follow the next steps:
Click the PIO icon at the left side bar. The project tasks should open.
Select
env:esp32doit-devkit-v1
(it may be slightly different depending on the board you’re using).
Expand the
Platform
menu.
Select
Build Filesyste
m Image.
Finally, click
Upload 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 the
main.cpp
file and upload it to your board.

#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() {

}
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:
MicroPython Programming with Arduino IDE (eBook)
More ESP32 Tutorials and Projects…