User Settings & Environment Variables

This page outlines configuring the OpenBB Platform with user settings and environment variables.

User Settings

User settings are stored locally, ~/.openbb_platform/, as a JSON file, user_settings.json. It is read upon initializing the Python client, or when the Fast API is authorized. If the file does not exist, it will be created on the first run.

This file stores:

credentials
preferences
defaults

This is an example of how it might look after setup:

{
    "credentials": {
        "fmp_api_key": "REPLACE",
        "polygon_api_key": "REPLACE",
    },
    "preferences": {
        "data_directory": "~/OpenBBUserData",
        "export_directory": "~/OpenBBUserData/exports",
        "metadata": true,
        "output_type": "OBBject"
    },
    "defaults": {
        "commands": {
            "/equity/price/historical": {
                "provider": "fmp"
            },
            "/equity/fundamental/balance": {
                "provider": [
                    "intrinio",
                    "fmp",
                    "polygon"
                ]
            },
        }
    }
}

Preferences

Preference	Default	Options	Description
data_directory	/home/OpenBBUserData	Any path.	When launching the application for the first time this directory will be created. It serves as the default location where the application stores usage artifacts such as logs and exports.
export_directory	/home/OpenBBUserData/exports	Any path.	The OpenBB Charting Extension provides the capability to export images in various formats. This is the directory where it attempts to save such exports.
cache_directory	/home/OpenBBUserData/cache	Any path.	The directory where http requests and database caches are stored, for functions with caching.
user_styles_directory	/home/OpenBBUserData/styles/user	Any path.	The OpenBB Charting Extension supports custom stylization. This directory is the location where it looks for user-defined styles. If no user styles are found in this directory the application will proceed with the default styles.
charting_extension	openbb_charting	["openbb_charting"]	Name of the charting extension to be used with the application.
chart_style	dark	["dark", "light"]	The default color style to use with the OpenBB Charting Extension plots. Options include "dark", and "light".
table_style	dark	["dark", "light"]	"The default color style to use with the OpenBB Charting Extension tables. Options are "dark", and "light""
metadata	true	[true, false]	Enables or disables the collection of metadata which provides information about operations including arguments duration route and timestamp. Disabling this feature may improve performance in cases where contextual information is not needed, or when the additional computation time and storage space are a concern.
output_type	OBBject	["OBBject", "dataframe", "numpy", "dict", "chart", "polars", "llm"]	Specifies the type of data the application will output when a command or endpoint is accessed. Note that choosing data formats only available in Python such as `dataframe`, `numpy`, or `polars` will render the application's API non-functional.
show_warnings	true	[true, false]	Enables or disables the display of warnings.

note

If an OpenBBUserData folder is not in the home directory, the application will create one on first run. The user preferences with paths all default to this folder - exports, styles, or data - and can be changed at any time to suit.
The OpenBBUserData will still be created even if preferences are not pointing to it, this is because the application needs a place to store logs and other artifacts.
One way to export files or images from the OpenBB Platform is to leverage that functionality from the OpenBB Charting Extension. The export_directory preference is the location where the extension will attempt to save CSV and image files.

Defaults

Here you can define provider defaults, and other parameters, for Python commands, if no argument is explicitly sent when the command runs. For 'provider', there are two formatting options:

Single provider: this provider will be selected by default for the given command.
Priority list: the first provider in the list with all required credentials setup will be used.

{
    ...
    "defaults": {
        "commands": {
            "/equity/price/historical": {
                "provider": "yfinance"
            },
            "/equity/fundamental/balance": {
                "provider": [
                    "yfinance",
                    "fmp",
                    "polygon"
                ]
            },
        }
    }
}

note

If no configuration is specified the command will use the default priority list. This is the list of available providers for the command sorted alphabetically.

Query Parameters

Individual parameters can also be defined in user_settings.json, and the values supplied will applied at runtime. The default will be ignored when the parameter is passed in the function call.

{
    ...
    "defaults": {
        "commands": {
            "/equity/price/historical": {
                "provider": "yfinance",
                "chart": true,
                "chart_params": {
                    "heikin_ashi": true,
                    "indicators": {
                        "sma": {
                            "length": [
                                21,
                                50
                            ]
                        },
                        "ema": {
                            "length": 150
                        }
                    }
                }
            },
            "/economy/cpi": {
                "provider": "oecd"
            }
        }
    }
}

important

Default parameters are somewhat limited in the FastAPI. Apart from 'provider', they are applicable only where parameters have been defined as Optional, with a default value of None.
Command docstrings and descriptions will not change according to items defined here.

Environment Variables

Environment variables are defined in a .env file. If this file does not exist, create it inside the same folder user_settings.json is located.

OPENBB_DEBUG_MODE: enables verbosity while running the program
OPENBB_AUTO_BUILD: enables automatic SDK package build on import
OPENBB_API_AUTH_EXTENSION: specifies which API authentication extension to use
OPENBB_API_AUTH: enables API authentication for command endpoints
OPENBB_API_USERNAME: sets API username
OPENBB_API_PASSWORD: sets API password

Variables can be defined for current session only.

import os
os.environ["OPENBB_DEBUG_MODE"] = "True"
from openbb import obb

Proxy Networks

See the HTTP settings below for how to define the proxy url.

System Settings

An additional configuration file, system_settings.json, is located in the same folder as user_settings.json, and can be created manually if it does not exist. The items below can be configured via this file, as a JSON dictionary.

API Settings

The, "api_settings", key is a nested dictionary, and is passed to the instance of FastAPI.

{
    "api_settings": {
        "version": "1",
        "title": "OpenBB Platform API",
        "description": "This is the OpenBB Platform API.",
        "terms_of_service": "http://example.com/terms/",
        "contact_name": "OpenBB Team",
        "contact_url": "https://openbb.co",
        "contact_email": "hello@openbb.co",
        "license_name": "AGPLv3",
        "license_url": "https://github.com/OpenBB-finance/OpenBB/blob/develop/LICENSE",
        "servers": [
            {
                "url": "",
                "description": "Local OpenBB development server"
            }
        ],
        "cors": {
            "allow_origins": [
                "*"
            ],
            "allow_methods": [
                "*"
            ],
            "allow_headers": [
                "*"
            ]
        },
        "prefix": "/api/v1"
    }
}

Logging Service

The OpenBB Platform logs anonymized records of function calls, and any error messages produced, to a unique file for the session, written to ~/OpenBBUserData/logs.

There are two settings that can be applied:

log_collect: Set as false to disable telemetry while still logging locally to file.
logging_suppress: Disables the file handler in the logging service and no log records are created.

{
    "logging_suppress": true,
    "log_collect": false
}

Python Settings

The python_settings key is a nested dictionary. It contains configurations for the docstring elements within the Python interface, as well as global HTTP and Uvicorn settings.

Additional keys and values can be supplied, however, unless they are specifically implemented by custom code, they will be ignored.

Docstring Sections

This configuration allows the user to include specific elements of the docstrings. Useful for reducing the context length when incorporating LLMs and function calling. The settings below are for the complete docstring, and are the default state.

{
    "python_settings": {
        "docstring_sections": ["description", "parameters", "returns", "examples"],
        "docstring_max_length": null
    }
}

HTTP

important

This section refers to settings available beginning OpenBB v4.4.0

Configurations within, python_settings["http"], apply to both, the requests, and aiohttp, libraries.

The settings are passed into the requests.Session object and the aiohttp.ClientSession object by:

openbb_core.provider.utils.helpers.make_request - Sync
openbb_core.provider.utils.helpers.amake_request - Async
openbb_core.provider.utils.helpers.amake_requests - Async (multiple requests)
Inserted to use with YFinance & Finviz library implementations.

Return a session object with the settings applied by:

openbb_core.provider.utils.helpers.get_requests_session
openbb_core.provider.utils.helpers.get_async_requests_session

tip

To use this configuration directly with the yFinance library, pass the session object, returned by get_requests_session, to the function's session parameter.

import yfinance as yf
from openbb_core.provider.utils.helpers import get_requests_session

session = get_requests_session()
ticker = yf.Ticker("AAPL", session=session)

Available settings:

Key	Type	Description
cafile	str	Path to a CA certificate file.
certfile	str	Path to a client certificate file.
keyfile	str	Path to a client key file.
password	str	Password for the client key file (aiohttp only).
verify_ssl	bool	Verify SSL certificates.
fingerprint	str	SSL fingerprint (aiohttp only).
proxy	str	Proxy URL.
proxy_auth	str, list	Proxy basic authentication (aiohttp only).
proxy_headers	dict	Proxy headers (aiohttp only).
timeout	int	Request timeout.
auth	str, list	Basic authentication.
headers	dict	Request headers.
cookies	dict	Dictionary of session cookies.

Any additional keys supplied will be ignored unless explicitly implemented via custom code.

Uvicorn

The, python_settings["uvicorn"], key covers the launch of FastAPI when using the following entry points:

Running the FastAPI as a Python module script.
- python -m openbb_core.api.rest_api
Running the openbb-api command.
- openbb-api

All settings are passed directly to uvicorn.run, and can be found in the Uvicorn documentation

important

Keyword arguments supplied to the command line will take priority over the settings in this configuration.

User Settings​

Preferences​

Defaults​

Query Parameters​

Environment Variables​

Proxy Networks​

System Settings​

API Settings​

Logging Service​

Python Settings​

Docstring Sections​

HTTP​

Available settings:​

Uvicorn​

User Settings

Preferences

Defaults

Query Parameters

Environment Variables

Proxy Networks

System Settings

API Settings

Logging Service

Python Settings

Docstring Sections

HTTP

Available settings:

Uvicorn