How to Configure OpenBB Development Mode and Debug Settings

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, 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), 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, 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 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 as SYSTEM_SETTINGS_PATH.

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/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.

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.

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) and the generic charting backend (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 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 and 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}