Common NetSurf user options

This document outlines the common configuration options supported by the NetSurf core.


The users configurations are generally stored in a "Choices" file and are loaded at browser startup. Most user interfaces provide a way to configure these parameters in a manner consistant with the toolkit in use.

The user choices are stored as a simple key:value list.

Each entry has a type, one of: boolean, integer, unsigned integer, hexadecimal colour value or string.

General Options

Option Key Type Default Description
http_proxy bool false An HTTP proxy should be used.
http_proxy bool false An HTTP proxy should be used.
http_proxy_host string NULL Hostname of proxy.
http_proxy_port int 8080 Proxy port.
http_proxy_auth int 0 Proxy authentication method.
http_proxy_auth_user string NULL Proxy authentication user name
http_proxy_auth_pass string NULL Proxy authentication password
http_proxy_noproxy string localhost Proxy omission list
font_size int 128 Default font size / 0.1pt.
font_min_size int 85 Minimum font size.
font_sans string NULL Default sans serif font
font_serif string NULL Default serif font
font_mono string NULL Default monospace font
font_cursive string NULL Default cursive font
font_fantasy string NULL Default fantasy font
accept_language string NULL Accept-Language header.
accept_charset string NULL Accept-Charset header.
memory_cache_size int 12MiB Preferred maximum size of memory cache in bytes.
disc_cache_size uint 1GiB Preferred expiry size of disc cache in bytes.
disc_cache_age int 28 Preferred expiry age of disc cache in days.
disc_cache_path string NULL Path to disc cache, NULL means to use system path
block_advertisements bool false Whether to block advertisements
do_not_track bool false Disable website tracking [1]
send_referer bool true Whether to send the referer HTTP header.
foreground_images bool true Whether to fetch foreground images
background_images bool true Whether to fetch background images
animate_images bool true Whether to animate images
enable_javascript bool false Whether to execute javascript
script_timeout int 10 Maximum time to wait for a script to run in seconds
expire_url int 28 How many days to retain URL data for.
font_default int 0 Default font family
ca_bundle string NULL ca-bundle location
ca_path string NULL ca-path location
cookie_file string NULL Cookie file location
cookie_jar string NULL Cookie jar location
homepage_url string NULL Home page location
search_url_bar bool false search web from url bar
search_provider int 0 default web search provider
url_suggestion bool true URL completion in url bar
window_x int 0 default x position of new windows
window_y int 0 default y position of new windows
window_width int 0 default width of new windows
window_height int 0 default height of new windows
window_screen_width int 0 width of screen when above options were saved
window_screen_height int 0 height of screen when above options were saved
toolbar_status_size int 6667 default size of status bar vs. h scroll bar
scale int 100 default window scale
incremental_reflow bool true Whether to reflow web pages while objects are fetching
min_reflow_period uint 25 Minimum time (in cs) between HTML reflows while objects are fetching
core_select_menu bool false Use core selection menu


Fetcher options

Option Key Type Default Description
max_fetchers int 24 Maximum simultaneous active fetchers
max_fetchers_per_host int 5 Maximum simultaneous active fetchers per host. (<=option_max_fetchers else it makes no sense) [2]
max_cached_fetch_handles int 6 Maximum number of inactive fetchers cached. The total number of handles netsurf will therefore have open is this plus option_max_fetchers.
suppress_curl_debug bool true Suppress debug output from cURL.
target_blank bool true Whether to allow target="_blank"
button_2_tab bool true Whether second mouse button opens in new tab.

[2] Note that rfc2616 section 8.1.4 says that there should be no more than two keepalive connections per host. None of the main browsers follow this as it slows page fetches down considerably. See

PDF / Print options

Option Key Type Deflt Description
margin_top int 10 top margin of exported page
margin_bottom int 10 bottom margin of exported page
margin_left int 10 left margin of exported page
margin_right int 10 right margin of exported page
export_scale int 70 scale of exported content
suppress_images bool false suppressing images in printed content
remove_backgrounds bool false turning off all backgrounds for printed content
enable_loosening bool true turning on content loosening for printed content
enable_PDF_compression bool true compression of PDF documents
enable_PDF_password bool false setting a password and encoding PDF documents

System colours

These are the css system colours which the browser also uses to style generated output.

Option Key Type Default
sys_colour_ActiveBorder colour 0x00d3d3d3
sys_colour_ActiveCaption colour 0x00f1f1f1
sys_colour_AppWorkspace colour 0x00f1f1f1
sys_colour_Background colour 0x006e6e6e
sys_colour_ButtonFace colour 0x00f9f9f9
sys_colour_ButtonHighlight colour 0x00ffffff
sys_colour_ButtonShadow colour 0x00aeaeae
sys_colour_ButtonText colour 0x004c4c4c
sys_colour_CaptionText colour 0x004c4c4c
sys_colour_GrayText colour 0x00505050
sys_colour_Highlight colour 0x00c00800
sys_colour_HighlightText colour 0x00ffffff
sys_colour_InactiveBorder colour 0x00f1f1f1
sys_colour_InactiveCaption colour 0x00e6e6e6
sys_colour_InactiveCaptionText colour 0x00a6a6a6
sys_colour_InfoBackground colour 0x008fdfef
sys_colour_InfoText colour 0x00000000
sys_colour_Menu colour 0x00f1f1f1
sys_colour_MenuText colour 0x004e4e4e
sys_colour_Scrollbar colour 0x00cccccc
sys_colour_ThreeDDarkShadow colour 0x00aeaeae
sys_colour_ThreeDFace colour 0x00f9f9f9
sys_colour_ThreeDHighlight colour 0x00ffffff
sys_colour_ThreeDLightShadow colour 0x00ffffff
sys_colour_ThreeDShadow colour 0x00d5d5d5
sys_colour_Window colour 0x00f1f1f1
sys_colour_WindowFrame colour 0x004e4e4e
sys_colour_WindowText colour 0x00000000