os – functions that an OS normally provides

The os module is a strict subset of the CPython os module. So, code written in CircuitPython will work in CPython but not necessarily the other way around.


Returns a named tuple of operating specific and CircuitPython port specific information.

class os._Uname

Bases: NamedTuple

The type of values that uname() returns

sysname :str
nodename :str
release :str
version :str
machine :str
os.chdir(path: str)None

Change current directory.


Get the current directory.

os.listdir(dir: str)str

With no argument, list the current directory. Otherwise list the given directory.

os.mkdir(path: str)None

Create a new directory.

os.remove(path: str)None

Remove a file.

os.rmdir(path: str)None

Remove a directory.

os.rename(old_path: str, new_path: str)str

Rename a file.

os.stat(path: str)Tuple[int, int, int, int, int, int, int, int, int, int]

Get the status of a file or directory.


On builds without long integers, the number of seconds for contemporary dates will not fit in a small integer. So the time fields return 946684800, which is the number of seconds corresponding to 1999-12-31.

os.statvfs(path: str)Tuple[int, int, int, int, int, int, int, int, int, int]

Get the status of a filesystem.

Returns a tuple with the filesystem information in the following order:

  • f_bsize – file system block size

  • f_frsize – fragment size

  • f_blocks – size of fs in f_frsize units

  • f_bfree – number of free blocks

  • f_bavail – number of free blocks for unprivileged users

  • f_files – number of inodes

  • f_ffree – number of free inodes

  • f_favail – number of free inodes for unprivileged users

  • f_flag – mount flags

  • f_namemax – maximum filename length

Parameters related to inodes: f_files, f_ffree, f_avail and the f_flags parameter may return 0 as they can be unavailable in a port-specific implementation.


Sync all filesystems.

os.urandom(size: int)str

Returns a string of size random bytes based on a hardware True Random Number Generator. When not available, it will raise a NotImplementedError.

os.sep :str

Separator used to delineate path components such as folder and file names.