storage – Storage management
The storage provides storage management functionality such as mounting and
unmounting which is typically handled by the operating system hosting Python.
CircuitPython does not have an OS, so this module provides this functionality
directly.
For more information regarding using the storage module, refer to the CircuitPython
Essentials Learn guide.
Available on these boards
- storage.mount(filesystem: VfsFat, mount_path: str, *, readonly: bool = False) None
Mounts the given filesystem object at the given path.
This is the CircuitPython analog to the UNIX
mountcommand.
- storage.umount(mount: str | VfsFat) None
Unmounts the given filesystem object or if mount is a path, then unmount the filesystem mounted at that location.
This is the CircuitPython analog to the UNIX
umountcommand.
- storage.remount(mount_path: str, readonly: bool = False, *, disable_concurrent_write_protection: bool = False) None
Remounts the given path with new parameters.
This can always be done from
boot.py. After boot, it can only be done when the host computer doesn’t have write access and CircuitPython isn’t currently writing to the filesystem. An exception will be raised if this is the case. Some host OSes allow you to eject a drive which will allow for remounting.Remounting after USB is active may take a little time because it “ejects” the drive for one query from the host. These queries happen every second or so.
- Parameters:
mount_path (str) – The path to remount.
readonly (bool) – True when the filesystem should be readonly to CircuitPython.
disable_concurrent_write_protection (bool) – When True, the check that makes sure the underlying filesystem data is written by one computer is disabled. Disabling the protection allows CircuitPython and a host to write to the same filesystem with the risk that the filesystem will be corrupted.
- storage.erase_filesystem(extended: bool | None = None) None
Erase and re-create the CIRCUITPY filesystem.
On boards that present USB-visible CIRCUITPY drive (e.g., SAMD21 and SAMD51), then call
microcontroller.reset()to restart CircuitPython and have the host computer remount CIRCUITPY.This function can be called from the REPL when CIRCUITPY has become corrupted.
- Parameters:
extended (bool) – On boards that support
dualbankmodule and theextendedparameter, the CIRCUITPY storage can be extended by setting this toTrue. If this isn’t provided or set toNone(default), the existing configuration will be used.
Note
New firmware starts with storage extended. In case of an existing filesystem (e.g. uf2 load), the existing extension setting is preserved.
Warning
All the data on CIRCUITPY will be lost, and CircuitPython will restart on certain boards.
- storage.disable_usb_drive() None
Disable presenting CIRCUITPY as a USB mass storage device. By default, the device is enabled and CIRCUITPY is visible, if USB is available. Must called in
boot.py, before USB is connected.
- storage.unsafe_disable_usb_drive() None
Disable presenting CIRCUITPY as a USB mass storage device even if in use. By default, the device is enabled and CIRCUITPY is visible. After the call, CIRCUITPY will be read/write to your code and from the REPL but not appear over USB.
Unlike
disable_usb_drive(),unsafe_disable_usb_drive()can be called aftercode.pystarts or from the REPL, after USB has started.Warning
If
unsafe_disable_usb_drive()is called when the host is in the middle of writing CIRCUITPY, filesystem corruption can occur. It is similar to the sudden physical removal of a USB drive. Before callingunsafe_disable_usb_drive(), make sure the host has finished any writes to CIRCUITPY.On Windows, do one of these:
Eject (“Safely Remove”) the CIRCUITPY drive.
Use a “sync” program, such as Sysinternals Sync.
Programmatically call
_commit()or_flushall()or similar.
On Linux or macOS, do one of these:
Eject (unmount) the CIRCUITPY drive.
Type
syncin a terminal.Programmatically call
sync()orfsync().
If none of the above are possible or convenient, wait several seconds to allow any writes to complete. This can be unreliable, as the interval to wait depends on the host operating system and how the drive is mounted. In some operating systems, you can specify that the drive be mounted as “sync on write”, so that all writes happen immediately.
When
unsafe_disable_usb_drive()is called after USB has started, the CIRCUITPY USB drive logical unit (LUN) will report as “not ready”, causing the host to unmount it. The drive can be made ready and available again by callingenable_usb_drive(). Whendisable_usb_driveis called aftercode.pystarts or in the REPL, the call will delay 2.5 seconds before returning, so that host has time to detect that the drive is not ready. The host polls the device approximately every one or two seconds.When the USB drive is disabled, CIRCUITPY becomes read/write, and can be written from user code or the REPL. This is easier than arranging for a
remount()inboot.py. Code editors and file uploaders can use this feature to write files via the REPL.If
unsafe_disable_usb_drive()is called inboot.py, it is identical to callingdisable_usb_drive().
- storage.enable_usb_drive() None
Enable presenting CIRCUITPY as a USB mass storage device. By default, the device is enabled and CIRCUITPY is visible, so you do not normally need to call this function in
boot.py.If you call
enable_usb_drive()aftercode.pystarts or in the REPL, you can reverse the effect of a previousunsafe_disable_usb_drive(). The CIRCUITPY drive will reappear to the host, and become read-only again if it was previously read-only.If you enable too many USB devices at once, you will run out of USB endpoints. The number of available endpoints varies by microcontroller. CircuitPython will go into safe mode after running
boot.pyto inform you if not enough endpoints are available.
- class storage.VfsFat(block_device: circuitpython_typing.BlockDevice)
Create a new VfsFat filesystem around the given block device.
- Parameters:
block_device – Block device the the filesystem lives on
- label: str
The filesystem label, up to 11 case-insensitive bytes. Note that this property can only be set when the device is writable by the microcontroller.
- readonly: bool
Truewhen the device is mounted as readonly by the microcontroller. This property cannot be changed, usestorage.remountinstead.
- static mkfs(block_device: circuitpython_typing.BlockDevice) None
Format the block device, deleting any data that may have been there.
Limitations: On SAMD21 builds,
mkfs()will raiseOSError(22)when attempting to format filesystems larger than 4GB. The extra code to format larger filesystems will not fit on these builds. You can still access larger filesystems, but you will need to format the filesystem on another device.
- ilistdir(path: str) Iterator[Tuple[AnyStr, int, int, int] | Tuple[AnyStr, int, int]]
Return an iterator whose values describe files and folders within
path
- mount(readonly: bool, mkfs: VfsFat) None
Don’t call this directly, call
storage.mount.
- umount() None
Don’t call this directly, call
storage.umount.