Using ESP8266 SPIFFS





Introduction: Using ESP8266 SPIFFS


Did you know each ESP8266 allows you to partition the system flash such that you can use it to store both code and support a file system?

This filing system can be used to store infrequently changing data such as; web pages, configurations, sensor calibration data etc.

This short Instructable details how to use SPIFFs, configure your Arduino IDE to upload files direct to your ESP8266 and figure out how much flash your device has.


What parts do I need?
System entry requirements;

  1. Your Arduino IDE has been set up to programme the ESP8266 (Setting Up the Arduino IDE to Program the ESP8266-01)
  2. An ESP8266-01 programming device (Practical Circuit Construction With Strip Board, Step 9 onwards)
  3. An ESP8266-01


What software do I need?

  • Arduino IDE 1.6.9


What skills do I need?
To set the system up, use the source code (provided) you will need the following;

  1. Knowledge of Arduino and it's IDE,
  2. Some knowledge of the ESP8266,
  3. Some Patience.


Topics covered

  1. So what is SPIFFS,
  2. Installing the Arduino ESP8266 filesystem uploader,
  3. How can I tell how much flash memory my ESP8266 has?
  4. How to upload files to your ESP8266 SPIFFS,
  5. How to test your SPIFFS and see it in action,
  6. Conclusion,
  7. References used.


Note 1 : Actually the ESP8266 flash also supports OTA updates, however the scope of this Instructable is limited to that of the SPIFFS functionality.

Note 2 : Whilst the examples given uses the ESP8266-01 it works equally well with the ESP8266-07, ESP8266-12, ESP8266-12E, ESP8266-13, as implied by the Instructable image.

Step 1: So What Is SPIFFS


Which stands for SPI Flash Filing System was designed for SPI flash devices on constrained embedded microprocessor systems with little RAM.

What SPIFFS does:

  • Specifically designed for low ram usage
  • Uses statically sized ram buffers, independent of number of files
  • Posix-like api: open, close, read, write, seek, stat, etc
  • Implements static wear leveling to prolong the life of system flash

What SPIFFS does not do:

  • SPIFFS does not support directories and uses a flat structure. Creating a file with path tmp/myfile.txt will create a file called tmp/myfile.txt instead of a myfile.txt under directory tmp.
  • It is not a real time stack. One write operation might take much longer than another. So is best used at start up, shut down or when time critical activities are not scheduled.
  • Presently, it does not detect or handle bad blocks.


Step 2: Installing the Arduino ESP8266 Filesystem Uploader

To install the Arduino ESP8266 filesystem uploader carry out the following;

    1. Go here and download a copy of ',
    2. Unzip the file,
    3. Drop the esp8266fs.jar file into Arduino tool directory (the path will look something like [home_dir]\Arduino\tools\ESP8266FS\tool\esp8266fs.jar),
      • In my case (as in pic 1 above);
      • C:\Users\Win 7\Documents\Arduino\tools\ESP8266FS\tool
      • I needed to create;
      • tools\ESP8266FS\tool\
      • Under;
      • C:\Users\Win 7\Documents\Arduino\
    4. Restart Arduino IDE.


    If you have got it correct you will see a new menu item 'ESP8266 Sketch Data Upload' under under 'Tools' as in pic 2 above.

    Step 3: How Can I Tell How Much Flash Memory My ESP8266 Has?

    Given most of these ESP8266 devices are sourced from Chinese suppliers who are less than forthcoming in releasing clear and concise product data, one way to figure out how big your flash is to read the chip details (assuming they haven't been scrubbed) and carrying out an internet search. I did this for two of my ESP8266-01s;

    • BergMicro 25Q80ASSIG 1602 : 8M/bit
    • Winbond 25Q80DVSIG 1626 : 8M/bit

    Here the former and latter are 1M byte. The problem with this method of identification is it simply won't work with the ESP8266 variants which house all the active components under an RF shielding can such as the ESP8266-07 and ESP8266-12E etc.

    Consequently, I found the most reliable and quickest method was to programme the device with the CheckFlashConfig.ino' sketch and review the output from the serial monitor as in Pic 1 above.



    You can download the full Arduino ESP8266 Core from here;

    and the CheckFlashConfig Source from here;

    Alternatively, copy given below.


    Step 4: How to Upload Files to Your ESP8266 SPIFFS

    Carryout the following to upload your files to the ESP8266 SPIFFS;

    1. Ensure you have a sub-directory within your sketch directory named 'data',
    2. Place the files you wish to upload into the 'data' directory,
    3. From 'Tools' menu, select the correct ESP8266 device and choose the 'Flash Size' with the SPIFFS you require ie. '1M (256K SPIFFS)'. See pics 1 and 2 above,
    4. Ensure the serial monitor dialogue box is closed,
    5. Prepare the ESP8266 device for upload;
      1. Hold down 'Flash',
      2. Pulse 'Reset'
      3. Release 'Flash',
    6. From Tools menu select 'ESP8266 Sketch Data Upload' See pic 3 top of image,
    7. Once upload is complete. Arduino IDE message window will show 100% upload. See pic 3 bottom of image.


    Note 1 : If an error message such as the one in Pic 4 occurs indicating 'SPIFFS Upload failed!'. Try unplugging/re-plugging your device's USB to serial adapter (FTDI) and repeating steps 1...7.

    Note 2 : SPIFFS content can be uploaded independently of programme code.

    Note 3 : If 'Flash Size' is changed, then programme code and SPIFFS will need to be reloaded.


    Step 5: How to Test Your SPIFFS and See It in Action

    To see a working example of SPIFFs carryout the following;

    1. Download the 'SPIFFsUsage.ino' sketch below,
    2. Unzip it and drop it into your Arduino sketches directory
      • Mine is here; C:\Users\Win 7\Documents\Arduino\My Progs
      • You will note there is a sub-directory named 'data' within which is a text filenamed 'testfile.txt'
    3. Select the flash geometry of your target system and the code space/SPIFFs size split you require (Tools->Flash Size),
    4. Ensure the serial monitor dialogue box is closed,
    5. Upload the text file to your ESP8266 device as described above in Step 4,
    6. Open the serial monitor dialogue box and set the baud rate to 115200,
    7. Upload 'SPIFFsUsage.ino' to ESP8266 device.

    Once you have completed the upload, the code will execute and your serial monitor dialogue will display text as in pic 1 above.

    It serves to show the contents of 'testfile.txt';

    1. Has been successfully uploaded,
    2. Located in the file system,
    3. Opened for read,
    4. Read until the end of file has been reached,
    5. Closed,
    6. Opened for append,
    7. A single line written to the file,
    8. The file has been re-read, displaying the recently appended line to the end of the file.


    Note : If the ESP8266 is powered down or reset, upon each successive execution a new line is automatically appended and displayed.

    Step 6: Conclusion

    Use of SPIFFS is a great way to store infrequently changing data though it should not be considered for applications requiring many write accesses as it will eventually cause flash to fail. A typical worked example of how long flash is likely to last is given here.

    Using the on-board filing system could save on I/O count where SPI SD card functionality is being considered for an I/O constrained device such as the ESP8266-01 where it is a very simple way to add secondary store without the need for 4 /I/O lines.

    Step 7: References Used



      • Clocks Contest

        Clocks Contest
      • Water Contest

        Water Contest
      • Creative Misuse Contest

        Creative Misuse Contest

      17 Discussions

      Useless for me. I expected to be able to check the actual size of the flash chip on my board. But Chip ID displays 2048 Bytes and ESP8266 Sketch data upload gives an error.

      4 replies

      Hmmm, perhaps if your comment had been polite I would have been inclined to help.

      Works fine for me and many others by all accounts.

      Good luck with the debugging.

      I'm sorry, I didn't mean to insult you. I ordered on Aliexpress the memory chips Winbond 25Q32BVSIG to upgrade the Sonoff Basic up to 4GB. But seller sent the chips marked SST25VF64C (8GB) and I was looking for a way to check the operation and the real memory size. ESP.getFlashChipRealSize() returns 2048 bytes and 'ESP8266 Sketch Data Upload' gives an 'out of memory' error.

      Therefore, I believe your method allows you to check the operation of the original chip with real characteristics. It's not good for my case. But I had already found a way to check the real size and it turned out that my chips were a relabeled fake with a real size of 4GB. I wrote a program using FS.h which creates a files of 100 kB in SPIFFS until it give an error "cannot create file". This shows the approximate memory size. I'm sorry again, good luck.

      Sounds like a good a way as any to check the flash size (though is obviously limited to 100K granularity, but don't suppose it matters over 4MB).

      I did some googling and found out that;

      - getFlashChipRealSize()

      - getFlashChipSize()

      Can return different values, real size being dependent upon the flash ID.

      Even the ESP Core documentation seems a little sketchy on this;

      I did an Instructable earlier where I up'ed the on-board flash size without any issues moving from 1MB to 4MB;

      I must have been lucky with my Ebay purchase.

      Just a word of advice, if you are going to replace the flash on a Sonoff device, tread carefully. The traces on the board are less than 1oz and can strip really easily. I used a heat gun and a good pair of tweezers.

      Thanks for the advice. I already soldered and checked the chip at a frequency of 80MHz.

      It turned out to write 60 files of 100 kilobytes each and it seems I was wrong about a fake. This is normal 8 GB SST25VF064C with Chip ID 4B25BF as described in the Datasheet. I tested several other boards - on D1 mini 4GB recorded 26 files, on the D1 mini Pro 16GB recorded 129 files.

      I would like to know how to clean the SPIFFs (text, image) files loaded in esp8266.

      Thank you

      1 reply


      is it possible to use this with OTA or HTTP update?


      1 reply

      nice one, but i cant get it to show up under tools....i created a tools folder in documents of arduino... nay other solution?

      1 reply

      Excellent Tutorial Steve. Very useful indeed. - Many thanks.

      1 reply

      Very useful information, right stuff I'm looking for. Thank you very much

      1 reply

      10 months ago

      Good info, I've uploaded a file but now I'm confused as to how to access it. What I uploaded was a gif file that I'd like to send to a web page. Can you elaborate on that or give direction as to where I might look to find that information? Thanks

      1 reply

      Hi JohnN3,

      This example shows how to upload, read and write from/to a file held in SPIFFs. Just that. I wrote the Instructable as it's not straight forward to use the SPIFFS. The text gives a reasonable description with the pit falls.

      If you want an example of how to make a webserver with the ESP8266, there is an example under ESP8266WebServer -> HelloServer or SDWebServer (this uses an SPI SD card not SPIFFs) you could follow.

      Though as I point out above the latter uses an SD card. It's easy to convert, just swap SD for SPIFFS.

      For my Instructable named 'WiFi IoT Temperature and Humidity Sensor. Part : 8 IoT, Home Automation'

      I use SPIFFS so you could use this a guide, though it is well integrated into the sensor code.

      I hope this helps