Skip to main content

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:

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",
        "request_timeout": 15,
        "metadata": true,
        "output_type": "OBBject"
    },
    "defaults": {
        "commands": {
            "/equity/price/historical": {
                "provider": "fmp"
            },
            "/equity/fundamental/balance": {
                "provider": [
                    "intrinio",
                    "fmp",
                    "polygon"
                ]
            },
        }
    }
}

Preferences​

PreferenceDefaultOptionsDescription
data_directory/home/OpenBBUserDataAny 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/exportsAny 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/cacheAny path.The directory where http requests and database caches are stored, for functions with caching.
user_styles_directory/home/OpenBBUserData/styles/userAny 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_extensionopenbb_charting["openbb_charting"]Name of the charting extension to be used with the application.
chart_styledark["dark", "light"]The default color style to use with the OpenBB Charting Extension plots. Options include "dark", and "light".
table_styledark["dark", "light"]"The default color style to use with the OpenBB Charting Extension tables. Options are "dark", and "light""
request_timeout15Any positive integer.Specifies the timeout duration for HTTP requests.
metadatatrue[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_typeOBBject["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_warningstrue[true, false]Enables or disables the display of warnings.
note
  • If a OpenBBUserData folder in 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:

  1. Single provider: this provider will be selected by default for the given command.
  2. Priority list: the first provider in the list with all required credentials setup will be used.
{
    ...
    "defaults": {
        "commands": {
            // single provider //
            "/equity/price/historical": {
                "provider": "fmp"
            },
            # priority list
            "/equity/fundamental/balance": {
                "provider": [
                    "intrinio",
                    "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​

An environment variable can be set, in the .env file, to direct the Requests library to a specific address and port.

HTTP_PROXY="<ADDRESS>" or HTTPS_PROXY="<ADDRESS>”

For example:

HTTP_PROXY="http://10.10.10.10:8000"

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.

Python Settings​

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
    }
}

API Settings​

This dictionary 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
}

On this page