[API categories](API-categories.md) | [API index](API-index.md)
# Application settings
Table of contents:
* [Introduction](#introduction)
* [Settings](#settings)
* [accept_language_list](#accept_language_list)
* [auto_zooming](#auto_zooming)
* [background_color](#background_color)
* [browser_subprocess_path](#browser_subprocess_path)
* [cache_path](#cache_path)
* [command_line_args_disabled](#command_line_args_disabled)
* [context_menu](#context_menu)
* [downloads_enabled](#downloads_enabled)
* [external_message_pump](#external_message_pump)
* [ignore_certificate_errors](#ignore_certificate_errors)
* [javascript_flags](#javascript_flags)
* [locale](#locale)
* [locales_dir_path](#locales_dir_path)
* [debug](#debug)
* [log_file](#log_file)
* [log_severity](#log_severity)
* [multi_threaded_message_loop](#multi_threaded_message_loop)
* [pack_loading_disabled](#pack_loading_disabled)
* [persist_session_cookies](#persist_session_cookies)
* [persist_user_preferences](#persist_user_preferences)
* [product_version](#product_version)
* [remote_debugging_port](#remote_debugging_port)
* [resources_dir_path](#resources_dir_path)
* [single_process](#single_process)
* [string_encoding](#string_encoding)
* [uncaught_exception_stack_size](#uncaught_exception_stack_size)
* [unique_request_context_per_browser](#unique_request_context_per_browser)
* [user_agent](#user_agent)
* [user_data_path](#user_data_path)
* [windowless_rendering_enabled](#windowless_rendering_enabled)
## Introduction
These settings can be passed when calling [cefpython](cefpython.md).Initialize() .
The default values of options that are suggested in descriptions may not always be correct, it may be best to set them explicitily.
There are hundreds of options that can be set through CEF/Chromium command line switches. These switches can be set programmatically by passing a dictionary with switches as second argument to [cefpython](cefpython.md).Initialize(). See the [CommandLineSwitches](CommandLineSwitches.md) wiki page for more information.
Issue #244 is to add even more configurable settings by exposing API
to Chromium Preferences.
## Settings
### accept_language_list
(string)
Comma delimited ordered list of language codes without any
whitespace that
will be used in the "Accept-Language" HTTP header. May be overridden on a
per-browser basis using the CefBrowserSettings.accept_language_list value.
If both values are empty then "en-US,en" will be used. Can be overridden
for individual CefRequestContext instances via the
CefRequestContextSettings.accept_language_list value.
### auto_zooming
(string)
Windows only. Perform automatic zooming of browser contents. Example values for auto_zooming (numeric value means a zoom level):
* "system_dpi" - use system DPI settings, see the [DpiAware](DpiAware.md) wiki page for more details.
* "0.0" (96 DPI)
* "1.0" (120 DPI)
* "2.0" (144 DPI)
* "-1.0" (72 DPI)
* "" - if cefpython detects that application is DPI aware it will automatically set `auto_zooming` to "system_dpi". If you do not wish such behavior set `auto_zooming` to an empty string. See the [DpiAware](DpiAware.md) wiki page for more details on that.
Example values that can be set in Win7 DPI settings (Control Panel Appearance and Personalization Display):
* Smaller 100% (Default) = 96 DPI = 0.0 zoom level
* Medium 125% = 120 DPI = 1.0 zoom level
* Larger 150% = 144 DPI = 2.0 zoom level
* Custom 75% = 72 DPI = -1.0 zoom level
### background_color
(int)
Opaque background color used for accelerated content. By default the
background color will be white. Only the RGB compontents of the specified
value will be used. The alpha component must greater than 0 to enable use
of the background color but will be otherwise ignored.
32-bit ARGB color value, not premultiplied. The color components are always
in a known order. Equivalent to the `SkColor` type.
### browser_subprocess_path
(string)
The path to a separate executable that will be launched for sub-processes.
By default the browser process executable is used. See the comments on
CefExecuteProcess() for details. Also configurable using the --browser-subprocess-path switch.
### cache_path
(string)
The location where cache data will be stored on disk. If empty then
browsers will be created in "incognito mode" where in-memory caches are
used for storage and no data is persisted to disk. HTML5 databases such as
localStorage will only persist across sessions if a cache path is
specified. Can be overridden for individual CefRequestContext instances via
the CefRequestContextSettings.cache_path value.
CEF flushes cookies or other cache data to disk every 30 seconds,
or immediately when [cefpython](cefpython.md).Shutdown() is called.
When this option is not set (empty string), a unique cache directory
will be created in the user's temp directory for each run of the application.
### command_line_args_disabled
(bool)
Set to true (1) to disable configuration of browser process features using
standard CEF and Chromium [command-line arguments](CommandLineSwitches.md). Configuration can still
be specified using CEF data structures or via the
`CefApp::OnBeforeCommandLineProcessing()` method.
### context_menu
(dict)
Configure mouse context menu. All dict values are of type bool and are True by default.
* `enabled` - whether to enable mouse context menu
* `navigation` - show the "Back", "Forward" and "Reload" items. The "Reload" option calls [Browser](Browser.md).`ReloadIgnoreCache`.
* `print` - show the "Print..." item
* `view_source` - show the "View source" item
* `external_browser` - show the "Open in external browser" and "Open frame in external browser" options. On Linux the external browser is not focused when opening url.
* `devtools` - show the "Developer Tools" option. See also ApplicationSettings.`remote_debugging_port`.
### downloads_enabled
(bool)
Default: True
Downloads are handled automatically. A default `SaveAs` file dialog provided by OS is displayed. See also the [DownloadHandler](DownloadHandler.md) wiki page.
### external_message_pump
(bool)
Default: False
EXPERIMENTAL: currently this option makes browser slower, so don't use it.
Reported issue in upstream, see Issue #246 for details.
It is recommended to use this option as a replacement for calls to
cefpython.MessageLoopWork(). CEF Python will do these calls automatically
using CEF's OnScheduleMessagePumpWork. This results in improved performance
and resolves some bugs. See Issue #246 for more details.
Description from upstream CEF:
> Set to true (1) to control browser process main (UI) thread message pump
> scheduling via the CefBrowserProcessHandler::OnScheduleMessagePumpWork()
> callback. This option is recommended for use in combination with the
> CefDoMessageLoopWork() function in cases where the CEF message loop must be
> integrated into an existing application message loop (see additional
> comments and warnings on CefDoMessageLoopWork). Enabling this option is not
> recommended for most users; leave this option disabled and use either the
> CefRunMessageLoop() function or multi_threaded_message_loop if possible.
### ignore_certificate_errors
(bool)
Set to true (1) to ignore errors related to invalid SSL certificates.
Enabling this setting can lead to potential security vulnerabilities like
"man in the middle" attacks. Applications that load content from the
internet should not enable this setting. Also configurable using the
"ignore-certificate-errors" [command-line switch](CommandLineSwitches.md).
Can be overridden for individual CefRequestContext instances via the
CefRequestContextSettings.ignore_certificate_errors value.
__IMPORTANT__: This option not only ignores all certificate errors,
but it also enables caching of content due to custom patch being
applied (read more in "NOTE ON CACHING" further down). If you don't
want this caching feature of insecure content then alternatively you
can ignore certificate errors using the
RequestHandler.[_OnCertificateError()](#_oncertificateerror)
callback. Note that disk caching is enabled only when the "cache_path"
option is set.
__NOTE ON CACHING__: the official CEF Python binary releases incorporate a patch
that changes the caching behavior on sites with SSL certificate errors
when used with this setting. Chromium by default disallows caching of
content when there is certificate error. CEF Python applies a patch to
Chromium sources to allow for caching even when there is certificate error,
but only when the "ignore_certificate_errors" option is set to True.
When it's set to False then the Chromium's caching behavior does not
change. Enabling caching with certificate errors is useful on local
private networks that use self-signed SSL certificates. See the
referenced CEF topic in [Issue #125](../issues/125) for more details.
### javascript_flags
(string)
Custom flags that will be used when initializing the V8 Javascript engine.
The consequences of using custom flags may not be well tested. Also
configurable using the --js-flags switch.
### locale
(string)
The locale string that will be passed to Webkit. If empty the default
locale of "en-US" will be used. This value is ignored on Linux where locale
is determined using environment variable parsing with the precedence order:
LANGUAGE, LC_ALL, LC_MESSAGES and LANG. Also configurable using the "lang"
[command-line switch](CommandLineSwitches.md).
### locales_dir_path
(string)
The fully qualified path for the locales directory. If this value is empty
the locales directory must be located in the module directory. This value
is ignored on Mac OS X where pack files are always loaded from the app
bundle Resources directory. Also configurable using the "locales-dir-path"
[command-line switch](CommandLineSwitches.md).
### debug
(bool)
Whether cefpython should display debug messages in console and write them to "log_file" (see the next option).
In previous versions of cefpython, this option was set by overwriting module's g_debug global variable, this way of setting is now deprecated.
### log_file
(string)
The directory and file name to use for the debug log. If empty a default
log file name and location will be used. On Windows and Linux a "debug.log"
file will be written in the main executable directory. On Mac OS X a
"~/Library/Logs/