Use alternative installation methods

Typically Chrome users install extensions by visiting an extension's listing in the Chrome Web Store and installing the extension directly from that page. In some cases, though, other installation flows may be more appropriate. For example:

An extension is associated with some other software, and the extension should be installed whenever the user installs that other software.
A network administrator wants to install the same extensions throughout their organization.

For the previous cases, Google Chrome supports the following extension installation methods:

Using a preferences JSON file (for macOS X and Linux only)
Using the Windows registry (for Windows only)

Both ways support installing an extension hosted at an update_URL. On Windows and macOS, the update_URL must point to the Chrome Web Store. When an extension is installed using these methods, Windows and macOS users will have to enable the extension using the following confirmation dialog:

External extension warning

On Linux, the preferences file can point to a Chrome Web Store extension, an externally hosted extension or a CRX extension file on the user's computer. Linux users won't be prompted to enable the extension; it is installed automatically.

Before you begin

Install from the Chrome Web Store

If you are distributing an extension hosted in the Chrome Web Store, you must first publish the extension. Then, make a note of the following:

The update URL— https://clients2.google.com/service/update2/crx. This URL points to the Chrome Web Store.
The extension's ID— This can be found in the Chrome Web Store URL of the extension.

Chrome Web Store item
id

Install from Local CRX file

If you are distributing to Linux users from a local file, you will need to package a CRX file and note the following information:

The extension ID— This can be found in the extension management page chrome://extensions.
The extension version— This appears in the extension management page chrome://extensions or in the manifest JSON file.

How to find extension
id and version

The location of the CRX file— This can either be a local directory or a network share. Make sure the file is available to the machine you want to install the extension on.

Install from a personal server

If you are distributing an extension hosted on a personal server for Linux users, you will need to follow the instructions for Installing extensions on Linux and note the following information:

The extension ID— This can be found in the extension management page chrome://extensions.
The update_url XML file path— This has to match the path of the update_url field declared in the manifest JSON file.

The following examples assume the version is 1.0 and the extension ID is aaabbbcccdddeeefff.

Use a preferences file

macOS

Create a JSON file with the name of the extension ID. For example: aaabbbcccdddeeefff.json
Place it in one of the following folders:

For a specific user

~USERNAME/Library/Application Support/Google/Chrome/External Extensions/

For all users

/Library/Application Support/Google/Chrome/External Extensions/
Specify the update URL with the field name "external_update_url". For example: json { "external_update_url": "https://clients2.google.com/service/update2/crx" }
Save the JSON file.
Launch Google Chrome and go to chrome://extensions; you should see the extension listed.

Note: The external extension file for all users is read-only if every directory in the path is owned by the user root, has the group admin or wheel, and is not world writable. The path must also be free of symbolic links. These restrictions prevent an unprivileged user from causing extensions to be installed for all users. See Troubleshooting permission problems.

Troubleshooting Mac OS permissions problems

On macOS, the external extensions files for all users are only read if file system permissions prevent unprivileged users from changing it. If you don't see external extensions installed when Chrome is launched, there may be a permissions problem with the external extensions preferences files. To see if this is the problem, follow these steps:

Launch the Console program. You can find it under /Applications/Utilities/Console.
If the leftmost icon in the Console says "Show Log List", click that icon. A second column appears at the left.
Click "Console Messages" in the left pane.
Search for the string Can not read external extensions. If there is a problem reading the external extensions files, you will see an error message. Look for another error message directly before it, which should explain the issue. For example, if you see the following error: "Path /Library/Application Support/Google/Chrome is owned by the wrong group", you need to use chgrp or the Finder's Get Info dialog to change the directory's group owner to the Administrator group.
After fixing the issue, relaunch Chrome. Test that the external extension is now installed. It is possible that one permissions error keeps Chrome from detecting a second error. If the external extension was not installed, repeat these steps until you don't see an error in the Console application.

Linux

Create a JSON file with the name of the extension ID. For example: aaabbbcccdddeeefff.json.
Place it in one of the following folders:
- /opt/google/chrome/extensions/
- /usr/share/google-chrome/extensions/
The following list describes extension installation from the Chrome Web Store, a CRX file or a personal server:
- To install a Chrome Web Store extension, specify the update URL with the field name "external_update_url". For example: json { "external_update_url": "https://clients2.google.com/service/update2/crx" }
- To install the extension from a CRX file, specify the location in "external_crx" and the version in "external_version". For example: json { "external_crx": "/home/share/extension.crx", "external_version": "1.0" }
- To install the extension hosted on a personal server, the "external_update_url" field has to point to the xml file, like in the following example: json { "external_update_url": "http://myhost.com/mytestextension/updates.xml" }
Save the JSON file.
Launch Google Chrome and go to chrome://extensions; you should see the extension listed.

Note: Use chmod if necessary to make sure that the aaabbbcccdddeeefff.json files are world-readable. Check the preference file common mistakes FAQ for additional help.

Supported Locales

If you would like to install extension only for some browser locales, you can list supported locales in field name "supported_locales". Locale may specify parent locale like "en", in this case the extension will be installed for all English locales like "en-US", "en-GB", etc. If another browser locale is selected that is not supported by the extension, the external extensions will be uninstalled. If "supported_locales" list is missing, the extension will be installed for any locale. For example:

{
  "external_update_url": "https://clients2.google.com/service/update2/crx",
  "supported_locales": [ "en", "fr", "de" ]
}

Use the Windows registry

Find or create the following key in the registry:

32-bit Windows

HKEY_LOCAL_MACHINE\Software\Google\Chrome\Extensions

64-bit Windows

HKEY_LOCAL_MACHINE\Software\Wow6432Node\Google\Chrome\Extensions
Create a new key (folder) under the Extensions key with the same name as the ID of your extension. For example: aaabbbcccdddeeefff.
In your extension key, create an "update_url" property and set it to the following value: json { "update_url": "https://clients2.google.com/service/update2/crx" }
Launch Chrome.
Go to chrome://extensions; you should see the extension listed.

Updating and uninstalling

Google Chrome scans the metadata entries in the preferences and registry each time the browser starts, and makes any necessary changes to the installed external extensions hosted in the Chrome Web Store.

To update a local CRX file extension to a new version, update the file, and then update the version in the preferences json file.

To uninstall your extension (for example, if your software is uninstalled), remove your preference file (for example, aaabbbcccdddeeefff.json) or the metadata from the registry.

FAQ

This section answers common questions about external extensions.

Is "pre-install" still supported by Google Chrome?

Yes, but only as an install from a Chrome Web Store update_url, not from a local CRX path. For more information, see App and Extension policies.

What are some common mistakes when installing with the preferences file?

Not specifying the same ID or version as the one listed in the CRX file.
The JSON file (for example, aaabbbcccdddeeefff.json) is in the wrong location or the ID specified does not match the extension ID.
Syntax error in JSON file (forgetting to separate entries with comma or leaving a trailing comma somewhere).
JSON file entry points to the wrong path to the CRX file (or path specified but no filename)
Backslashes in UNC path are not escaped. For example, "\\server\share\file" is wrong; it should be "\\\\server\\share\\extension".
Permissions problems on a network share.

What are some common mistakes when installing with the registry?

Not specifying the same ID as the one listed in the Chrome Web Store.
Key created in the wrong location in the registry.
Registry entry points to the wrong path to the CRX file in the Chrome Web Store.
Permissions problems on a network share.
Not all instances of Chrome are closed. Try rebooting your computer after setting the registry.

What if the user uninstalls the extension?

If the user uninstalls the extension through the UI, it will no longer be installed or updated on each startup. In other words, the external extension is blocklisted.

How do I get off the blocklist?

If the user uninstalls your extension, you should respect that decision. However, if you (the developer) accidentally uninstalled your extension through the UI, you can remove the blocklist tag by installing the extension normally through the UI, and then uninstalling it.