Language: EN


How to serve compressed content in Gzip with ESP8266 or ESP32

We continue with the entries of ESP8266 and ESP32, this time seeing how to serve compressed static content in Gzip from the SPIFFS memory.

We will refer to ESP8266, but the same code is compatible for ESP32, adjusting the name of the libraries. At the end you have the code for both ESP8266 and ESP32.

In the previous post we have seen how to serve files (html, js, css, or any other) from the SPIFFS file system. We already anticipated that it was the appropriate way to serve static content.

However, it is convenient for us to optimize the size of the served files. It is especially important in any type of server, but even more so in a low-power processor like the ESP8266.

There are several options such as minifying the served content. Another of the most common and convenient options is to compress the served files usually in Gzip format.

In fact, most servers serve compressed files, and modern browsers are prepared to decompress the files transparently for the user.

Serving compressed files allows to send files between 2 to 5 times smaller (approx), which means less load for the server, less bandwidth, and better transmission speed. The effort to decompress is small and falls on the clients, not on the server.

Is it possible to modify our server from SPIFFS to serve Gzip files? Of course it is. In fact, it works wonders and is a very convenient measure to significantly improve the performance of the ESP8266 as a server. In fact, it is very simple.

The main Sketch remains the same as the previous example, with the following content.

#include <ESP8266WiFi.h>
#include <ESP8266WebServer.h>
#include <FS.h>   // Include the SPIFFS library
#include "config.h"  // Replace with your network data
#include "Server.hpp"
#include "ESP8266_Utils.hpp"

void setup(void)

void loop(void)

We have to modify our definition of the server behavior in ‘Server.hpp’ to use the new and improved version.

ESP8266WebServer server(80);

#include "ESP8266_Utils_Server.hpp"

void handleNotFound() {
  server.send(404, "text/plain", "Not found");

void InitServer()
   server.onNotFound([]() {
      if (!HandleFileReadGzip(server.uri()))
   Serial.println("HTTP server started");

The biggest change is in the ‘ESP8266_Utils_Server.hpp’ file, where we have added the HandleFileReadGzip function that will allow us to manage the requests for Gzip files.

As we can see, this function checks if the requested file exists. If it doesn’t exist, it checks if the compressed version (.gz) exists. If it still doesn’t find it, it returns ‘File Not Found’.

bool HandleFileReadGzip(String path) 
  if (path.endsWith("/")) path += "index.html";
  Serial.println("handleFileRead: " + path);
  if (SPIFFS.exists(path)) 
    ServeFile(path, GetContentType(path));
    return true;
      String pathWithGz = path + ".gz";
        ServeFile(pathWithGz, GetContentType(path));
        return true;
  Serial.println("\tFile Not Found");
  return false;

On the other hand, we take the files from our ‘data’ folder and compress them in Gzip format, for example, using the 7-Zip program for example.


We upload everything and access the served page to verify that, indeed, it works and we are serving compressed files. It’s that simple!


Compressing the files is a very important improvement, especially if we include “heavy” JavaScript libraries and frameworks in our code. We will notice a very significant performance improvement.

This is already a fairly functional and appropriate example of how to serve static content with the ESP8266. But is it possible to improve it? Of course it is. And we will see it in the next post by making an asynchronous server. See you soon!

Download the code

All the code from this post is available for download on Github.


Version for ESP8266:

Version for ESP32: