bokeh.settings#

Control global configuration options with environment variables. A global settings object that other parts of Bokeh can refer to.

Defined Settings#

Settings are accessible on the bokeh.settings.settings instance, via accessor methods. For instance:

settings.minified()

Bokeh provides the following defined settings:

allowed_ws_origin#

Type:

List[String]

Env var:

BOKEH_ALLOW_WS_ORIGIN

Default:

[]

Dev Default:

(Unset)

A comma-separated list of allowed websocket origins for Bokeh server applications.

auth_module#

Type:

String

Env var:

BOKEH_AUTH_MODULE

Default:

None

Dev Default:

(Unset)

A path to a Python modules that implements user authentication functions for the Bokeh server.

Warning

The contents of this module will be executed!

browser#

Type:

String

Env var:

BOKEH_BROWSER

Default:

None

Dev Default:

‘none’

The default browser that Bokeh should use to show documents with.

Valid values are any of the predefined browser names understood by the Python standard library webbrowser module.

version#

Type:

String

Env var:

BOKEH_CDN_VERSION

Default:

None

Dev Default:

(Unset)

What version of BokehJS to use with CDN resources.

See the Resources class reference for full details.

chromedriver_path#

Type:

String

Env var:

BOKEH_CHROMEDRIVER_PATH

Default:

None

Dev Default:

(Unset)

The name of or full path to chromedriver’s executable.

This is used to allow bokeh.io.export to work on systems that use a different name for chromedriver, like chromedriver-binary or chromium.chromedriver (or its variant, which is used for example by Snap package manager; see https://snapcraft.io/).

docs_cdn#

Type:

String

Env var:

BOKEH_DOCS_CDN

Default:

None

Dev Default:

(Unset)

The version of BokehJS that should be use for loading CDN resources when building the docs.

To build and display the docs using a locally built BokehJS, use local. For example:

BOKEH_DOCS_CDN=local make clean serve

Will build a fresh copy of the docs using the locally built BokehJS and open a new browser tab to view them.

Otherwise, the value is interpreted a version for CDN. For example:

BOKEH_DOCS_CDN=1.4.0rc1 make clean

will build docs that use BokehJS version 1.4.0rc1 from CDN.

docs_version#

Type:

String

Env var:

BOKEH_DOCS_VERSION

Default:

None

Dev Default:

(Unset)

The Bokeh version to stipulate when building the docs.

This setting is necessary to re-deploy existing versions of docs with new fixes or changes.

ico_path#

Type:

Ico Path

Env var:

BOKEH_ICO_PATH

Default:

‘default’

Dev Default:

‘default-dev’

Configure the file path to a .ico file for the Bokeh server to use as a favicon.ico file.

The value should be the full path to a .ico file, or one the following special values:

  • default to use the default project .ico file

  • none to turn off favicon.ico support entirely

ignore_filename#

Type:

Bool

Env var:

BOKEH_IGNORE_FILENAME

Default:

False

Dev Default:

(Unset)

Whether to ignore the current script filename when saving Bokeh content.

log_level#

Type:

String

Env var:

BOKEH_LOG_LEVEL

Default:

‘info’

Dev Default:

‘debug’

Set the log level for JavaScript BokehJS code.

Valid values are, in order of increasing severity:

  • trace

  • debug

  • info

  • warn

  • error

  • fatal

minified#

Type:

Bool

Env var:

BOKEH_MINIFIED

Default:

True

Dev Default:

False

Whether Bokeh should use minified BokehJS resources.

nodejs_path#

Type:

String

Env var:

BOKEH_NODEJS_PATH

Default:

None

Dev Default:

(Unset)

Path to the Node executable.

NodeJS is an optional dependency that is required for PNG and SVG export, and for compiling custom extensions. Bokeh will try to automatically locate an installed Node executable. Use this environment variable to override the location Bokeh finds, or to point to a non-standard location.

validate_doc#

Type:

Bool

Env var:

BOKEH_VALIDATE_DOC

Default:

True

Dev Default:

(Unset)

whether Bokeh should perform validation checks on documents.

Setting this value to False may afford a small performance improvement.

pretty#

Type:

String

Env var:

BOKEH_PRETTY

Default:

False

Dev Default:

True

Whether JSON strings should be pretty-printed.

py_log_level#

Type:

Log Level

Env var:

BOKEH_PY_LOG_LEVEL

Default:

‘none’

Dev Default:

‘debug’

The log level for Python Bokeh code.

Valid values are, in order of increasing severity:

  • trace

  • debug

  • info

  • warn

  • error

  • fatal

  • none

resources#

Type:

String

Env var:

BOKEH_RESOURCES

Default:

‘cdn’

Dev Default:

‘server’

What kind of BokehJS resources to configure, e.g inline or cdn

See the Resources class reference for full details.

rootdir#

Type:

String

Env var:

BOKEH_ROOTDIR

Default:

None

Dev Default:

(Unset)

Root directory to use with relative resources

See the Resources class reference for full details.

default_server_host#

Type:

String

Env var:

BOKEH_DEFAULT_SERVER_HOST

Default:

‘localhost’

Dev Default:

(Unset)

Allows to define the default host used by Bokeh’s server and resources.

default_server_port#

Type:

Int

Env var:

BOKEH_DEFAULT_SERVER_PORT

Default:

5006

Dev Default:

(Unset)

Allows to define the default port used by Bokeh’s server and resources.

secret_key#

Type:

String

Env var:

BOKEH_SECRET_KEY

Default:

None

Dev Default:

(Unset)

A long, cryptographically-random secret unique to a Bokeh deployment.

serialize_include_defaults#

Type:

String

Env var:

BOKEH_SERIALIZE_INCLUDE_DEFAULTS

Default:

False

Dev Default:

(Unset)

Whether to include default values when serializing HasProps instances.

This is primarily useful for testing, debugging serialization/protocol and other internal purpose.

sign_sessions#

Type:

String

Env var:

BOKEH_SIGN_SESSIONS

Default:

False

Dev Default:

(Unset)

Whether the Bokeh server should only allow sessions signed with a secret key.

If True, BOKEH_SECRET_KEY must also be set.

simple_ids#

Type:

Bool

Env var:

BOKEH_SIMPLE_IDS

Default:

True

Dev Default:

(Unset)

Whether Bokeh should use simple integers for model IDs (starting at 1000).

If False, Bokeh will use UUIDs for object identifiers. This might be needed, e.g., if multiple processes are contributing to a single Bokeh Document.

ssl_certfile#

Type:

String

Env var:

BOKEH_SSL_CERTFILE

Default:

None

Dev Default:

(Unset)

The path to a certificate file for SSL termination.

ssl_keyfile#

Type:

String

Env var:

BOKEH_SSL_KEYFILE

Default:

None

Dev Default:

(Unset)

The path to a private key file for SSL termination.

ssl_password#

Type:

String

Env var:

BOKEH_SSL_PASSWORD

Default:

None

Dev Default:

(Unset)

A password to decrypt the SSL keyfile, if necessary.

validation_level#

Type:

Validation Level

Env var:

BOKEH_VALIDATION_LEVEL

Default:

‘none’

Dev Default:

(Unset)

Whether validation checks should log or raise exceptions on errors and warnings.

Valid values are:

  • none: no exceptions raised (default).

  • errors: exception raised on errors (but not on warnings)

  • all: exception raised on both errors and warnings

xsrf_cookies#

Type:

Bool

Env var:

BOKEH_XSRF_COOKIES

Default:

False

Dev Default:

(Unset)

Whether to enable Tornado XSRF cookie protection on the Bokeh server. This is only applicable when also using an auth module or custom handlers. See

https://www.tornadoweb.org/en/stable/guide/security.html#cross-site-request-forgery-protection

for more information about XSRF protection in Tornado. All PUT, POST, and DELETE handlers will need to be appropriately instrumented when this setting is active.

Precedence#

Setting values are always looked up in the following prescribed order:

immediately supplied values

These are values that are passed to the setting:

settings.minified(minified_val)

If minified_val is not None, then it will be returned, as-is. Otherwise, if None is passed, then the setting will continue to look down the search order for a value. This is useful for passing optional function parameters that are None by default. If the parameter is passed to the function, then it will take precedence.

previously user-set values

If the value is set explicitly in code:

settings.minified = False

Then this value will take precedence over other sources. Applications may use this ability to set values supplied on the command line, so that they take precedence over environment variables.

user-specified config override file

Values from a YAML configuration file that is explicitly loaded:

settings.load_config("/path/to/bokeh.yaml)

Any values from bokeh.yaml will take precedence over the sources below. Applications may offer command line arguments to load such a file. e.g. bokeh serve --use-config myconf.yaml

environment variable

Values found in the associated environment variables:

BOKEH_MINIFIED=no bokeh serve app.py
local user config file

Bokeh will look for a YAML configuration file in the current user’s home directory ${HOME}/.bokeh/bokeh.yaml.

global system configuration (not yet implemented)

Future support is planned to load Bokeh settings from global system configurations.

local defaults

These are default values defined when accessing the setting:

settings.resources(default="server")

Local defaults have lower precedence than every other setting mechanism except global defaults.

global defaults

These are default values defined by the setting declarations. They have lower precedence than every other setting mechanism.

If no value is obtained after searching all of these locations, then a RuntimeError will be raised.

API#

There are a few methods on the settings object:

class Settings[source]#
bokehjs_path() → Path[source]#

The location of the BokehJS source tree.

bokehjsdir() → str[source]#

The location of the BokehJS source tree.

Deprecated since version 3.4.0: Use bokehjs_path() method instead.

css_files() → list[str][source]#

The CSS files in the BokehJS directory.

js_files() → list[str][source]#

The JS files in the BokehJS directory.

load_config(location: PathLike) → None[source]#

Load a user-specified override config file.

The file should be a YAML format with key: value lines.

secret_key_bytes() → bytes | None[source]#

Return the secret_key, converted to bytes and cached.