If you encounter an "out of disk space" error when trying to save a file to your CIRCUITPY drive, you are running into a limitation of your non-volatile Flash storage.

If you've already deleted all unnecessary files, there are a few other techniques to save some space on your Flash storage on your board. Your library files, bitmaps and font files will likely be the largest users of your file storage space, here's some ways to address those.

Shrink your code

When writing and editing CircuitPython code, you create text files with .py as the file extension. These .py files are normal ASCII text files that can be edited with any text editor. CircuitPython interprets your code from this text and executes your commands. Additionally CircuitPython can execute "partially compiled" .mpy files. These .mpy files take up about half the storage space of the original raw text .py file.

Use pre-compiled Libraries
To save storage space, be sure to use the .mpy file for all your libraries placed in the /lib folder. For all libraries supported by Adafruit or in the Community bundle, they are already prepared into the .mpy format. You can find these pre-compiled libraries in the bundles found on the CircuitPython.org website.

If you need to make a change to any library code, download the .py version of the library file from the library's repository, edit it and copy the file into the /lib folder of your CIRCUITPY drive. Always be sure to delete any of the pre-compiled .mpy versions of the library file to prevent a conflict with your custom .py library version.

When to pre-compile your own code
If your project uses a lot of lines of code, you can convert your .py files to .mpy files to save on storage space.

Creating .mpy files takes a little more work. The benefit of CircuitPython is so you can iterate your code quickly, so it's fastest to develop your code in text using .py files. Only convert your code to .mpy when you really need to save the last bit of Flash storage space. Or break your code into logical chunks and pre-compile only the code files that are stable, so you can iterate quickly on the new parts of your code. Here are the instructions for creating your own .mpy files.

Note: The code.py file cannot be pre-compiled, but feel free to organize your code so that the code.py calls other files and libraries that are precompiled. Precompile your main code to mycode.mpy, then your code.py can be simplified down to:

import mycode

Bitmap files

Graphical projects should use lots of cool graphics, so you will likely use bitmap files in your project. These files often take up a large amount of storage space, so try these techniques if you want to reduce their filesizes.

Reduce color depth

Bitmap files used in CircuitPython projects are sometimes formatted as indexed bitmaps.  To shrink the indexed bitmap filesize consider reducing the "color depth", the number of colors that are used in your bitmap.  Small changes to the color depth won't make an impact, but reducing the color depth by multiple factors of two or four may reduce filesize.

Replace bitmaps with generated graphics
If you have background images with grids or simple shapes (lines, rectangles, circles and polygons) consider using the vectorio module to generate the graphics using code. The vectorio module is memory-optimized, so it also can reduce your RAM use too. Here are the the graphics objects available in the vectorio module.

Font files

Font files contain the graphical data necessary to display text labels on your LCD and matrix displays. These font files can take up significant storage space, especially for larger font sizes. If you use font files in your project, here are a couple techniques to consider when looking to free up Flash storage space.

Multiple font sizes

If you're using multiple font files, consider reducing the number of font files and use the scale option that is provided in the label and bitmap_label in the Adafruit CircuitPython Display Text library. This technique will lose some resolution for your text labels, but it will reduce the total storage required for your font files.

BDF and PCF font files
If you're using font files, shrink the font file size by eliminating un-needed character glyphs from your files. Here's a guide to shrinking font file sizes. If you're using BDF-format font files and you've deleted unnecessary characters, you're ready to save even more storage space by converting to PCF format. Converting to PCF format, saves file storage space and the fonts will load faster too. Win, win!

Remove hidden files

Sometimes your operating system will automatically create hidden files on your CircuitPython's file storage. Here is a guide that explains how to find and remove those hidden files that can fill up your CIRCUITPY drive.


This guide was first published on Apr 17, 2021. It was last updated on Mar 08, 2024.

This page (Flash storage: Space-saving tips) was last updated on Mar 08, 2024.

Text editor powered by tinymce.