Skip to content

Latest commit

 

History

History
204 lines (163 loc) · 20.6 KB

chrome-flags-for-tools.md

File metadata and controls

204 lines (163 loc) · 20.6 KB
Raw

Chrome Flags for Tooling

Many tools maintain a list of runtime flags for Chrome to configure the environment. This file is an attempt to document all chrome flags that are relevant to tools, automation, benchmarking, etc.

All use cases are different, so you'll have to choose which flags are most appropriate.

Here's a Nov 2022 comparison of what flags all these tools use.

Commonly unwanted browser features

  • --disable-client-side-phishing-detection: Disables client-side phishing detection
  • --disable-component-extensions-with-background-pages: Disable some built-in extensions that aren't affected by --disable-extensions
  • --disable-default-apps: Disable installation of default apps
  • --disable-extensions: Disable all chrome extensions
  • --disable-features=InterestFeedContentSuggestions: Disables the Discover feed on NTP
  • --disable-features=Translate: Disables Chrome translation, both the manual option and the popup prompt when a page with differing language is detected.
  • --hide-scrollbars: Hide scrollbars from screenshots.
  • --mute-audio: Mute any audio
  • --no-default-browser-check: Disable the default browser check, do not prompt to set it as such
  • --no-first-run: Skip first run wizards
  • --ash-no-nudges: Avoids blue bubble "user education" nudges (eg., "… give your browser a new look", Memory Saver)
  • --disable-search-engine-choice-screen: Disable the 2023+ search engine choice screen

Task throttling

  • --disable-background-timer-throttling: Disable timers being throttled in background pages/tabs
  • --disable-backgrounding-occluded-windows: Normally, Chrome will treat a 'foreground' tab instead as backgrounded if the surrounding window is occluded (aka visually covered) by another window. This flag disables that.
  • --disable-features=CalculateNativeWinOcclusion: Disable the feature of: Calculate window occlusion on Windows will be used in the future to throttle and potentially unload foreground tabs in occluded windows.
  • --disable-hang-monitor: Suppresses hang monitor dialogs in renderer processes. This flag may allow slow unload handlers on a page to prevent the tab from closing.
  • --disable-ipc-flooding-protection: Some javascript functions can be used to flood the browser process with IPC. By default, protection is on to limit the number of IPC sent to 10 per second per frame. This flag disables it. https://crrev.com/604305
  • --disable-renderer-backgrounding: This disables non-foreground tabs from getting a lower process priority This doesn't (on its own) affect timers or painting behavior. karma-chrome-launcher#123

Web platform behavior

  • --aggressive-cache-discard
  • --allow-running-insecure-content
  • --disable-back-forward-cache: Disables the BackForwardCache feature.
  • --disable-features=AcceptCHFrame: Disable accepting h2/h3 ACCEPT_CH Client Hints frames.
  • --disable-features=AutoExpandDetailsElement: Removed in Sept 2022.
  • --disable-features=AvoidUnnecessaryBeforeUnloadCheckSync: If enabled, this feature results in the browser process only asking the renderer process to run beforeunload handlers if it knows such handlers are registered. With kAvoidUnnecessaryBeforeUnloadCheckSync, content does not report a beforeunload handler is present. A ramification of this is navigations that would normally check beforeunload handlers before continuing will not, and navigation will synchronously continue.
  • --disable-features=BackForwardCache: Disable the bfcache.
  • --disable-features=HeavyAdPrivacyMitigations: Disables the privacy mitigations for the heavy ad intervention. This throttles the amount of interventions that can occur on a given host in a time period. It also adds noise to the thresholds used. This is separate from the intervention feature so it does not interfere with field trial activation, as this blocklist is created for every user, and noise is decided prior to seeing a heavy ad.
  • --disable-features=IsolateOrigins
  • --disable-features=LazyFrameLoading
  • --disable-features=ScriptStreaming: V8 script streaming
  • --no-process-per-site: Disables renderer process reuse (across tabs of the same site).
  • --enable-precise-memory-info: Make the values returned to window.performance.memory more granular and more up to date in shared worker. Without this flag, the memory information is still available, but it is bucketized and updated less frequently. This flag also applys to workers.
  • --js-flags=--random-seed=1157259157: Initialize V8's RNG with a fixed seed.
  • --use-fake-device-for-media-stream: Use fake device for Media Stream to replace camera and microphone
  • --use-fake-ui-for-media-stream: Bypass the media stream infobar by selecting the default device for media streams (e.g. WebRTC). Works with --use-fake-device-for-media-stream.
  • --use-file-for-fake-video-capture=<path-to-file>: Use file for fake video capture (.y4m or .mjpeg) Needs --use-fake-device-for-media-stream

Interactivity suppression

  • --autoplay-policy=...: Value of user-gesture-required to not autoplay video. Value of no-user-gesture-required to always autoplay video.
  • --deny-permission-prompts: Suppress all permission prompts by automatically denying them.
  • --disable-external-intent-requests: Disallow opening links in external applications
  • --disable-features=GlobalMediaControls: Hide toolbar button that opens dialog for controlling media sessions.
  • --disable-features=ImprovedCookieControls: Disables an improved UI for third-party cookie blocking in incognito mode.
  • --disable-notifications: Disables the Web Notification and the Push APIs.
  • --disable-popup-blocking: Disable popup blocking. --block-new-web-contents is the strict version of this.
  • --disable-prompt-on-repost: Reloading a page that came from a POST normally prompts the user.
  • --noerrdialogs: Suppresses all error dialogs when present.

Catch-all automation

  • --enable-automation: Disable a few things considered not appropriate for automation. (Original design doc, though renamed here) codesearch. Note that some projects have chosen to avoid using this flag: web-platform-tests/wpt/#6348, crbug.com/1277272
    • sets window.navigator.webdriver to true within all JS contexts. This is also set when using --headless, --remote-debugging-pipe and --remote-debugging-port=0 (yes, specifically 0).
    • disables bubble notification about running development/unpacked extensions (source)
    • disables the password saving UI (which covers the usecase of the defunct --disable-save-password-bubble flag)
    • disables infobar animations (source)
    • disables auto-reloading on network errors (source)
    • enables the CDP method Browser.getBrowserCommandLine.
    • avoids showing these 4 infobars: ShowBadFlagsPrompt, GoogleApiKeysInfoBarDelegate, ObsoleteSystemInfoBarDelegate, LacrosButterBar
    • adds this infobar: image ... which is known to adversely affect screenshots.
  • --test-type: Basically the 2014 version of --enable-automation. codesearch
    • It avoids creating application stubs in ~/Applications on mac.
    • It makes exit codes slightly more correct
    • windows navigation jumplists arent updated https://crbug.com/389375
    • doesn't start some chrome StartPageService
    • disables initializing chromecast service
    • "Component extensions with background pages are not enabled during tests because they generate a lot of background behavior that can interfere."
    • when quitting the browser, it disables additional checks that may stop that quitting process. (like unsaved form modifications or unhandled profile notifications..)
  • --remote-debugging-pipe: more secure than using protocol over a websocket
  • --remote-debugging-port=...: With a value of 0, Chrome will automatically select a useable port and will set navigator.webdriver to true.
  • --silent-debugger-extension-api: Does not show an infobar when a Chrome extension attaches to a page using chrome.debugger page. Required to attach to extension background pages.

General

  • --enable-logging=stderr: Logging behavior slightly more appropriate for a server-type process.
  • --log-level=0: 0 means INFO and higher. 2 is the most verbose. Protip: Use --enable-logging=stderr --v=2 and you may spot additional components active that you may want to disable.
  • --user-data-dir=...: Directory where the browser stores the user profile.

Chromium Annoyances

  • --disable-features=MediaRouter: Avoid the startup dialog for Do you want the application “Chromium.app” to accept incoming network connections?. Also disables the Chrome Media Router which creates background networking activity to discover cast targets. A superset of disabling DialMediaRouteProvider.
  • --password-store=basic: Avoid potential instability of using Gnome Keyring or KDE wallet. chromium/linux/password_storage.md https://crbug.com/571003
  • --use-mock-keychain: Use mock keychain on Mac to prevent the blocking permissions dialog abou: Chrome wants to use your confidential information stored in your keychain

Background networking

  • --disable-background-networking: Disable various background network services, including extension updating,safe browsing service, upgrade detector, translate, UMA
  • --disable-breakpad: Disable crashdump collection (reporting is already disabled in Chromium)
  • --disable-component-update: Don't update the browser 'components' listed at chrome://components/
  • --disable-domain-reliability: Disables Domain Reliability Monitoring, which tracks whether the browser has difficulty contacting Google-owned sites and uploads reports to Google.
  • --disable-features=AutofillServerCommunication: Disables autofill server communication. This feature isn't disabled via other 'parent' flags.
  • --disable-features=CertificateTransparencyComponentUpdater
  • --disable-sync: Disable syncing to a Google account
  • --enable-crash-reporter-for-testing: Used for turning on Breakpad crash reporting in a debug environment where crash reporting is typically compiled but disabled.
  • --metrics-recording-only: Disable reporting to UMA, but allows for collection
  • --disable-features=OptimizationHints: Disable the Chrome Optimization Guide and networking with its service API
  • --disable-features=DialMediaRouteProvider: A weaker form of disabling the MediaRouter feature. See that flag's details.
  • --no-pings: Don't send hyperlink auditing pings

Rendering & GPU

  • --allow-pre-commit-input: Allows processing of input before a frame has been committed. Used by headless. https://crbug.com/987626
  • --deterministic-mode: An experimental meta flag. This sets the below indented flags which put the browser into a mode where rendering (border radius, etc) is deterministic and begin frames should be issued over DevTools Protocol. codesearch
    • --run-all-compositor-stages-before-draw
    • --disable-new-content-rendering-timeout
    • --enable-begin-frame-control
    • --disable-threaded-animation
    • --disable-threaded-scrolling
    • --disable-checker-imaging
    • --disable-image-animation-resync
  • --disable-features=PaintHolding: Don't defer paint commits (normally used to avoid flash of unstyled content)
  • --disable-partial-raster: https://crbug.com/919955
  • --disable-skia-runtime-opts: Do not use runtime-detected high-end CPU optimizations in Skia.
  • --in-process-gpu: Saves some memory by moving GPU process into a browser process thread
  • --use-gl="swiftshader": Select which implementation of GL the GPU process should use. Options are: desktop: whatever desktop OpenGL the user has installed (Linux and Mac default). egl: whatever EGL / GLES2 the user has installed (Windows default - actually ANGLE). swiftshader: The SwiftShader software renderer.

Window & screen management

  • --block-new-web-contents: All pop-ups and calls to window.open will fail.
  • --force-color-profile=srgb: Force all monitors to be treated as though they have the specified color profile.
  • --new-window: Launches URL in new browser window.
  • --window-position=0,0: Specify the initial window position: --window-position=x,y
  • --window-size=1600,1024: Sets the initial window size. Provided as string in the format "800,600".

Process management

  • --disable-features=DestroyProfileOnBrowserClose: Disable the feature of: Destroy profiles when their last browser window is closed, instead of when the browser exits.
  • --disable-features=site-per-process: Disables OOPIF. https://www.chromium.org/Home/chromium-security/site-isolation
  • --no-service-autorun: Disables the service process from adding itself as an autorun process. This does not delete existing autorun registrations, it just prevents the service from registering a new one.
  • --process-per-tab: Doesn't do anything. Use --single-process instead.
  • --single-process: Runs the renderer and plugins in the same process as the browser.

Headless

  • --headless: Run in headless mode, i.e., without a UI or display server dependencies.
  • --headless=new: New, native Headless mode. (previously, --headless=chrome)
  • --no-sandbox: Sometimes used with headless, though not recommended.
  • --disable-dev-shm-usage: Often used in Lambda, Cloud Functions scenarios. (pptr issue, crbug)
  • --disable-gpu: Was often used along with --headless, but as of 2021, isn't needed.

Removed flags

  • --disable-add-to-shelf: Removed June 2017
  • --disable-background-downloads: Removed Oct 2014.
  • --disable-browser-side-navigation: Removed. It disabled PlzNavigate.
  • --disable-datasaver-prompt: Removed
  • --disable-desktop-notifications: Removed
  • --disable-device-discovery-notifications: Removed. Avoided messages like "New printer on your network". Replaced with --disable-features=MediaRouter.
  • --disable-features=TranslateUI: Removed as TranslateUI changed to Translate in Sept 2020.
  • --disable-infobars: Removed May 2019
  • --disable-save-password-bubble: Removed May 2016
  • --disable-search-geolocation-disclosure: Removed.
  • --disable-translate: Removed April 2017 Used to disable built-in Google Translate service.
  • --ignore-autoplay-restrictions: Removed December 2017 Can use --autoplay-policy=no-user-gesture-required instead.
  • --safebrowsing-disable-auto-update: Removed Nov 2017

Sources

The canonical list of Chrome command-line switches on peter.sh (maintained by the Chromium team)

FYI: (Probably) all flags are defined in files matching the pattern of *_switches.cc.

Set Preferences

Many Chrome settings are defined in a JSON file located at USER_DATA_DIR/Default/Preferences. Browse your own Preferences file to see what's in there; some, but not all, preferences are defined in pref_names.h

If you wanted to launch a fresh Chrome profile with some Preferences set, for example: disable DevTools source-map fetching:

mkdir -p your_empty_user_data_dir/Default/
echo '{"devtools":{"preferences":{"jsSourceMapsEnabled":"false","cssSourceMapsEnabled":"false"}}}' > your_empty_user_data_dir/Default/Preferences

chrome --user-data-dir=your_empty_user_data_dir ...

Feature Flags FYI

Chromium and Blink use feature flags to disable/enable many features at runtime. Chromium has ~400 features that can be toggled with --enable-features / --disable-features. https://niek.github.io/chrome-features/ presents all of them very clearly.

Independently, Blink has many features that can be toggled with commandline switches: --enable-blink-features / --disable-blink-features.