Edit

Share via

Configure Microsoft Edge using Initial Preferences settings for the first run

  • Article

Use the information in this article to configure Microsoft Edge Initial Preferences settings on your Windows devices.

Configure policy settings on Windows

Starting Microsoft Edge release 93, Microsoft supports a limited number of Initial Preferences (formerly named "Master Preferences") to help admins configure browsers for the first run. For more information, see the supported settings in the following Preference settings table.

When deployed, Initial Preferences act as the default browser settings on managed devices. These preferences are the settings preferred by admins to be used as default browser settings for the first run.

Note

Initial preferences can be changed by users and aren't available for some devices because they aren't joined to an Active Directory® domain.

Some examples of initial preferences settings include initial configuration of a default homepage or tabs with specific URLs.

Preferences are only copied once from the initial_preferences file, changes made to this file after configuration aren't respected. If a setting is managed by a Microsoft Edge policy and configured in the initial_preferences file, the policy always takes precedence.

Preference settings

The following table shows the settings that Microsoft Edge currently supports.

Preferences Category Setting
Bookmark_bar show_apps_shortcut
show_managed_bookmarks
show_on_all_tabs
Bookmarks editing_enabled
Browser / clear_data browsing_history
browsing_history_basic"
cache
cache_basic
cookies
download_history
form_data
passwords
History browsing_history
cache
cookies
download_history
form_data
hosted_apps_data
passwords
site_settings
Browser first_run_tabs
dark_theme
show_toolbar_bookmarks_button
show_toolbar_collections_button
show_toolbar_downloads_button
show_home_button
show_prompt_before_closing_tabs
show_toolbar_history_button
default_search_provider [default_search_provider] enabled
Fullscreen Allowed
homepage Homepage_url
homepage_is_newtabpage homepage_is_newtabpage
Session restore_on_startup
startup_urls
Extensions Extensions: settings

1: Download an example initial_preferences file

To get started, download the "Policy" file from the Microsoft Edge Enterprise landing page. Extract the files in the download, and then open the initial_preferences file in the examples folder. The next screenshot shows the policy file options that are available to download

Microsoft Edge policy files available for download.

2: Customize and validate the initial_preferences file

Customize the preferences settings in the downloaded initial_preferences file and validate the changes to make sure that there are no errors in the JSON code. If you find errors, check the syntax and structure of the initial_preferences file, make corrections, and check it again. Few example tools to validate JSON, Online JSON Tools or JSON editing in Visual Studio Code.

3: Deploy preferences to users' computer

Deploy the initial_preferences file to users' devices at the same time as Microsoft Edge is deployed and put the file in the following location on the device.

Windows (AMD64 and ARM64)

Channel Location
Stable "C:\Program Files (x86)\Microsoft\Edge\Application"
Beta "C:\Program Files (x86)\Microsoft\Edge Beta\Application"
Canary "%LOCALAPPDATA%\Microsoft\Edge SxS\Application"
Dev "C:\Program Files (x86)\Microsoft\Edge Dev\Application"

Note

The initial_preferences file needs to be deployed to the same folder as the msedge.exe file on users' Windows computers.

macOS

Channel Location
Stable "~/Library/Application Support/Microsoft Edge/Microsoft Edge Initial Preferences"
Beta "~/Library/Application Support/Microsoft Edge Beta/Microsoft Edge Initial Preferences"
Canary "~/Library/Application Support/Microsoft Edge Canary/Microsoft Edge Initial Preferences"
Dev "~/Library/Application Support/Microsoft Edge Dev/Microsoft Edge Initial Preferences"

Important notes: MSI/PKG Deployment and initial_preferences interaction

Initial preferences will only take effect after the initial_preferences file is deployed before the browser's first run by the end users.

See also