Environment Variables

CircuitPython 8.0.0 introduces support for environment variables. Environment variables are commonly used to store “secrets” such as Wi-Fi passwords and API keys. This method does not make them secure. It only separates them from the code.

CircuitPython supports these by mimicking the dotenv CPython library. Other languages such as Javascript, PHP and Ruby also have dotenv libraries.

These libraries store environment variables in a .env file. Here is a simple example:

# Comment
is multiple lines'

CircuitPython uses the .env at the drive root (no folder) as the environment. User code can access the values from the file using os.getenv(). It is recommended to save any values used repeatedly in a variable because os.getenv() will parse the /.env on every access.

CircuitPython behavior

CircuitPython will also read the environment to configure its behavior. Other keys are ignored by CircuitPython. Here are the keys it uses:


Default BLE name the board advertises as, including for the BLE workflow.


On boards with Espressif microcontrollers with PSRAM (also called SPIRAM), permanently reserve a portion of PSRAM for use by esp-idf. This storage is removed from the CircuitPython “heap” and is available for allocation by esp-idf routines in the core instead. Generally, only set this to a non-zero value when it is required by a specific core module.


Password required to make modifications to the board from the Web Workflow.


TCP port number used for the web HTTP API. Defaults to 80 when omitted.


Wi-Fi password used to auto connect to CIRCUITPY_WIFI_SSID.


Wi-Fi SSID to auto-connect to even if user code is not running.