# How to Configure OpenBB Development Mode and Debug Settings

> Configure OpenBB development mode and debug settings by enabling debug_mode in system_settings.json or exporting the DEBUG_MODE environment variable. Unlock advanced features for seamless development.

- Repository: [OpenBB/OpenBB](https://github.com/OpenBB-finance/OpenBB)
- Tags: how-to-guide
- Published: 2026-03-06

---

**Enable OpenBB development mode by setting `debug_mode` to `true` in `~/.openbb/system_settings.json` or by exporting the `DEBUG_MODE` environment variable before launching the platform.**

OpenBB controls debug and development behavior centrally through the **SystemSettings** model in the OpenBB-finance/OpenBB repository. The `debug_mode` boolean field defaults to `False` and is persisted in a JSON configuration file, while the **Env** helper provides a runtime fallback for environment-based overrides. Understanding these mechanisms allows developers to toggle verbose logging and diagnostic output from charting backends without modifying source code.

## How OpenBB Debug Settings Work

The debug configuration flows through three architectural layers in the OpenBB platform core.

### SystemSettings Model

In [`openbb_platform/core/openbb_core/app/model/system_settings.py`](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/core/openbb_core/app/model/system_settings.py), the **SystemSettings** Pydantic model defines the `debug_mode: bool` field with a default value of `False`. This field serializes to `~/.openbb/system_settings.json`, which serves as the persistent configuration store. The platform reads this file at startup to determine global behavior.

### ChartingSettings Propagation

When the platform initializes **ChartingSettings** ([`openbb_platform/core/openbb_core/app/model/charts/charting_settings.py`](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/core/openbb_core/app/model/charts/charting_settings.py)), it consumes the `debug_mode` value from SystemSettings. If the JSON setting is absent, it falls back to the `DEBUG_MODE` environment variable exposed by the `Env` helper. This value propagates to all visualization backends.

### Backend Initialization

Charting extensions receive the debug flag during instantiation. In [`openbb_platform/obbject_extensions/charting/openbb_charting/core/plotly_ta/ta_class.py`](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/obbject_extensions/charting/openbb_charting/core/plotly_ta/ta_class.py), the Plotly-TA wrapper starts with `debug=self._charting_settings.debug_mode`. Similarly, the generic charting backend in [`openbb_platform/obbject_extensions/charting/openbb_charting/charting.py`](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/obbject_extensions/charting/openbb_charting/charting.py) initializes with the same debug parameter, enabling diagnostic output when active.

## Methods to Enable Development Mode

You can activate debug mode persistently, temporarily for a single session, or programmatically within a Python script.

### Persistent Configuration via JSON

Edit the system settings file directly to enable debug mode across all future sessions. The file location is defined in [`openbb_platform/core/openbb_core/app/constants.py`](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/core/openbb_core/app/constants.py) as **SYSTEM_SETTINGS_PATH**.

```python
import json
from pathlib import Path
from openbb_core.app.constants import SYSTEM_SETTINGS_PATH

# Load existing settings or initialize empty dictionary

settings = json.loads(SYSTEM_SETTINGS_PATH.read_text()) if SYSTEM_SETTINGS_PATH.exists() else {}

# Enable development mode

settings["debug_mode"] = True

# Persist changes

SYSTEM_SETTINGS_PATH.write_text(json.dumps(settings, indent=4))
print(f"Debug mode enabled in {SYSTEM_SETTINGS_PATH}")

```

### Temporary Session via Environment Variable

Export `DEBUG_MODE` before launching the CLI or a Python interpreter to enable debugging for a single session without modifying configuration files. The `Env` helper (`openbb_core.env.Env`) reads this variable at runtime.

```bash

# Bash/Zsh

export DEBUG_MODE=1
openbb

```

Any non-empty value for `DEBUG_MODE` evaluates to `True` when parsed by the environment helper.

### Programmatic Toggle in Python

For testing or conditional debugging, set the environment variable programmatically before importing OpenBB components. This approach ensures the `Env` singleton picks up the flag during module initialization.

```python
import os
from openbb_core.env import Env

# Set debug mode for current process

os.environ["DEBUG_MODE"] = "true"

# Verify Env helper reads the value

assert Env().DEBUG_MODE is True

# Subsequent imports will use debug settings

from openbb_charting import chart

```

## Verifying Debug Mode is Active

Confirm the current configuration by instantiating **SystemSettings**. Note that these settings are immutable after loading and reflect the JSON state at initialization time.

```python
from openbb_core.app.model.system_settings import SystemSettings

settings = SystemSettings()
print("Debug mode active:", settings.debug_mode)

```

If you set the environment variable but see `False`, restart your Python session to ensure the `Env` helper re-reads the environment.

## How Debug Mode Affects Charting Backends

When `debug_mode` is enabled, OpenBB charting extensions expose additional diagnostic information. The **Plotly-TA** wrapper ([`ta_class.py`](https://github.com/OpenBB-finance/OpenBB/blob/main/ta_class.py)) and the generic charting backend ([`charting.py`](https://github.com/OpenBB-finance/OpenBB/blob/main/charting.py)) both initialize with `debug=True`, triggering verbose logging of figure generation steps, data transformation pipelines, and layout calculations. This visibility is essential when troubleshooting custom extensions or diagnosing data processing errors in development workflows.

## Summary

- **SystemSettings** in [`system_settings.py`](https://github.com/OpenBB-finance/OpenBB/blob/main/system_settings.py) controls the central `debug_mode` boolean, persisted to `~/.openbb/system_settings.json`.
- **ChartingSettings** propagates this value to visualization backends, falling back to the `DEBUG_MODE` environment variable via the **Env** helper.
- Enable debug mode persistently by editing the JSON file, temporarily via `export DEBUG_MODE=1`, or programmatically with `os.environ`.
- Charting backends in [`plotly_ta/ta_class.py`](https://github.com/OpenBB-finance/OpenBB/blob/main/plotly_ta/ta_class.py) and [`charting.py`](https://github.com/OpenBB-finance/OpenBB/blob/main/charting.py) respect the flag to provide verbose diagnostic output.

## Frequently Asked Questions

### What is the difference between system_settings.json and environment variables for debug mode?

The JSON file provides persistent configuration that survives across sessions, while the `DEBUG_MODE` environment variable offers temporary, process-scoped debugging without altering configuration files. If both are set, the JSON value typically takes precedence in SystemSettings, but the Env helper provides a fallback for ChartingSettings when the JSON is absent.

### Does enabling debug mode affect OpenBB performance?

Yes. Debug mode increases verbosity in charting backends and core components, which can introduce marginal latency during figure generation and logging operations. Disable debug mode in production environments to maintain optimal execution speed.

### Where exactly is the system_settings.json file located?

The file resides at `~/.openbb/system_settings.json` on Unix-like systems. The exact path is programmatically accessible via `SYSTEM_SETTINGS_PATH` from `openbb_core.app.constants`, ensuring your scripts reference the correct location regardless of platform.