1 <h1>Other Deployment Options</h1>
4 Usually, users install their own extensions.
5 But sometimes you might want an extension
6 to be installed automatically.
7 Here are two typical cases:
12 An extension is associated with some other software,
13 and the extension should be installed
14 whenever the user installs that other software.
15 The extension could also be uninstalled
16 when the user removes that other software.
19 A network admin wants to install the same extensions
20 throughout the company.
25 An extension that's installed automatically is known as an
26 <em>external extension</em>.
27 Google Chrome supports two ways of
28 installing external extensions:
32 <li> Using a preferences JSON file (Mac OS X and Linux only)</li>
33 <li> Using the Windows registry (Windows only) </li>
37 Both ways support installing an extension hosted at an
38 <code>update_URL</code>.
39 In the Windows registry,
40 the <code>update_URL</code> must point to the Chrome Web Store
41 where the extension is hosted.
45 In the preferences file,
46 it can point to your own server where you are hosting the extension
47 (see <a href="autoupdate#update_url">autoupdating</a>).
48 The preferences JSON file also supports installing
49 an extension from a <code>.crx</code> extension
50 file on the user's computer
51 (see <a href="hosting">hosting</a>).
56 <b>Install extensions from your website:</b>
57 The safest option for your users is to publish your extension
58 in the Chrome Web Store.
59 Instead of hosting your own extension,
60 publish it in the store, and link to the store install using
61 <a href="https://developers.google.com/chrome/web-store/docs/inline_installation">inline installation</a>.
64 <h2 id="prereqs">Before you begin</h2>
67 First, <a href="/webstore/publish">publish</a>
68 the extension in the Chrome Web Store,
69 or package a <a href="packaging"><code>.crx</code> file</a>
70 and make sure that it installs successfully.
75 <b>Windows installs must come from Chrome Web Store:</b><br>
77 no external installs are allowed from a path to a local <code>.crx</code>
78 (see <a href="http://blog.chromium.org/2013/11/protecting-windows-users-from-malicious.html">Protecting Windows users from malicious extensions</a>).
83 <a href="autoupdate#update_url">update URL</a>, ensure that the extension
84 is properly <a href="hosting">hosted</a>.
88 Before you edit the preferences file or the registry,
89 make a note of the following:
93 <li> The intended <b>location</b> of the extension's <code>.crx</code> file,
94 or the update URL from which it is served </li>
95 <li> The extension's <b>version</b>
96 (from the manifest file or the <b>chrome://extensions</b> page) </li>
97 <li> The extension's <b>ID</b>
98 (from the <b>chrome://extensions</b> page
99 when you've loaded the packed extension) </li>
103 The following examples assume the version is <code>1.0</code>
104 and the ID is <code>aaaaaaaaaabbbbbbbbbbcccccccccc</code>.
107 <h2 id="preferences">Using a preferences file</h2>
112 <b>Mac OS X and Linux only:</b>
113 Do not use the preferences file for Windows.
114 Use <a href="#registry">Windows registry</a> instead.
118 <li>If you are installing from a file, make the <code>.crx</code> extension
119 file available to the machine you want to install the extension on.
120 (Copy it to a local directory or to a network share for example,
121 <code>\\server\share\extension.crx</code>
122 or <code>/home/share/extension.crx</code>.)
125 <li>Create a file with the following name in one of the folders listed below:
126 <code>aaaaaaaaaabbbbbbbbbbcccccccccc.json</code> where the file name (without the extension)
127 corresponds to your extension's ID.
128 The location depends on the operating system.
131 <dd>For a specific user: <code>~USERNAME/Library/Application Support/Google/Chrome/External Extensions/</code><br>
132 For all users: <code>/Library/Application Support/Google/Chrome/External Extensions/</code>
133 <p>The external extension file for all users is read only if every directory in the path is owned by the user <code>root</code>, has the group <code>admin</code> or <code>wheel</code>, 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 <a href="#troubleshooting">troubleshooting</a> for details.</p>
135 <b>Note:</b> The above path for all users was added in Chrome 16. Prior versions used a different path:<br/>
136 <code>/Applications/Google Chrome.app/Contents/Extensions/</code>
137 This path was deprecated in version 17. Support was removed in version 20. Use one of the paths above instead.</p>
141 <dd> <code>/opt/google/chrome/extensions/</code> <br>
143 <dd> <code>/usr/share/google-chrome/extensions/</code> <br>
144 <b>Note:</b> Use <code>chmod</code> if necessary
145 to make sure that the <code>aaaaaaaaaabbbbbbbbbbcccccccccc.json</code> files
151 <li>If you are installing from a file, specify the extension's location and version with fields
152 named "external_crx" and "external_version" in the file created above.
157 "external_crx": "/home/share/extension.crx",
158 "external_version": "1.0"
165 each <code>\</code> character in the location.
167 <code>\\server\share\extension.crx</code> would be
168 <code>"\\\\server\\share\\extension.crx"</code>.
172 If you are installing from an update URL, specify the extension's update URL
173 with field name "external_update_url".
177 "external_update_url": "http://myhost.com/mytestextension/updates.xml"
180 If you would like to install extension only for some browser locales,
181 you can list supported locales in field name "supported_locale". Locale may
182 specify parent locale like "en", in this case the extension will be
183 installed for all English locales like "en-US", "en-GB", etc.
184 If another browser locale is selected that is not supported by the extension,
185 the external extensions will be uninstalled. If "supported_locales" list
186 is missing, the extension will be installed for any locale.
190 "external_update_url": "http://myhost.com/mytestextension/updates.xml",
191 "supported_locales": [ "en", "fr", "de" ]
194 <li>Save the JSON file.</li>
195 <li>Launch Google Chrome and go to <b>chrome://extensions</b>;
196 you should see the extension listed. </li>
201 Previous versions of Google Chrome used an
202 <code>external_extensions.json</code> file to specify which extensions to
203 install. This file has been deprecated in favor of individual <code>.json</code>
204 files, one per extension.
207 <h3 id="troubleshooting">Troubleshooting Mac OS permissions problems</h3>
209 <p>On Mac OS, the external extensions files for all users are only read if file system permissions prevent unprivileged users from changing it. If you do not 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:</p>
212 <li> Launch the Console program. You can find it under /Applications/Utilities/Console. </li>
213 <li> If the leftmost icon in the Console says "Show Log List", click that icon. A second column appears at the left. </li>
214 <li> Click "Console Messages" in the left pane. </li>
215 <li> Search for the string <b>Can not read external extensions</b>. If there is a problem reading the external extensions files, you will see an error message. Look for another error message directly above it, which should explain the issue. For example, if you see the following error:
216 "Path /Library/Application Support/Google/Chrome is owned by the wrong group", you need to use <code>chgrp</code> or the Finder's Get Info dialog to change the directory's group owner to the Administrator group.</li>
217 <li> 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 do not see an error in the Console application.
220 <h2 id="registry">Using the Windows registry</h2>
223 <li>Find or create the following key in the
226 <li> 32-bit Windows: <code>HKEY_LOCAL_MACHINE\Software\Google\Chrome\Extensions</code> </li>
227 <li> 64-bit Windows: <code>HKEY_LOCAL_MACHINE\Software\Wow6432Node\Google\Chrome\Extensions</code> </li>
231 <li>Create a new key (folder)
232 under the <b>Extensions</b> key with the
233 same name as the ID of your extension
234 (for example, <code>aaaaaaaaaabbbbbbbbbbcccccccccc</code>).
236 <li>In your extension key,
237 create a property, "update_url", and set it to the value:
238 "https://clients2.google.com/service/update2/crx"
239 (this points to your extension's crx in the Chrome Web Store):
241 "update_url": "https://clients2.google.com/service/update2/crx"
244 <li>Launch the browser and go to
245 <b>chrome://extensions</b>; you should
246 see the extension listed. </li>
249 <h2 id="updating">Updating and uninstalling</h2>
251 <p>Google Chrome scans the metadata entries
252 in the preferences and registry
253 each time the browser starts, and makes
254 any necessary changes to the installed
255 external extensions. </p>
257 <p>To update your extension to a new version,
258 update the file, and then update the version
259 in the preferences or registry. </p>
261 <p>To uninstall your extension
262 (for example, if your software is uninstalled),
263 remove your preference file (aaaaaaaaaabbbbbbbbbbcccccccccc.json)
264 or the metadata from the registry. </p>
266 <h2 id="faq">FAQ</h2>
269 This section answers common questions about external extensions.
272 <p><b>Will the methodology for allowing a “pre-install” still be supported
273 by Google Chrome from M33 onwards?</b></p>
274 <p>Yes, but only as an install from a Chrome Web Store
275 <code>update_URL</code>,
276 not from a local file path.</p>
278 <p><b>Can I specify a URL as a path to the external extension?</b> </p>
279 <p>Yes, use the <a href="#preferences">preferences JSON</a> file
280 for Mac OS X and Linux; the <a href="#registry">registry</a> for Windows.
281 The extension must be hosted as explained in
282 <a href="hosting">hosting</a>.
283 In the preferences file,
284 use the "external_update_url" property to point to an
285 <a href="autoupdate#update_manifest">update manifest</a> that has the URL for your
287 In the Windows registry,
288 use the "update_url" property.</p>
290 <p><b>What are some common mistakes when installing with the preferences
294 Not specifying the same id/version
295 as the one listed in the <code>.crx</code> </li>
297 The .json file (<code>aaaaaaaaaabbbbbbbbbbcccccccccc.json</code>) is in
298 the wrong location or the ID specified does not match the extension ID.
300 Syntax error in JSON file
301 (forgetting to separate entries with comma or
302 leaving a trailing comma somewhere) </li>
304 JSON file entry points to the wrong path
305 to the <code>.crx</code> (or path specified but no filename) </li>
307 Backslashes in UNC path not escaped
308 (for example, <code>"\\server\share\file"</code> is wrong;
309 it should be <code>"\\\\server\\share\\extension"</code>) </li>
311 Permissions problems on a network share </li>
314 <p><b>What are some common mistakes when installing with the registry?</b> </p>
316 <li>Not specifying the same id/version
317 as the one listed in the Chrome Web Store </li>
318 <li>Key created in the wrong location in the registry </li>
319 <li>Registry entry points to the wrong path
320 to the <code>.crx</code> file in the Chrome Web Store</li>
321 <li>Permissions problems on a network share </li>
324 <p><b>How do I update my native binaries and extension in-step?</b></p>
325 <p>Previously when off-store extensions were supported,
326 it was possible to have the native binaries and the extension be updated in lock step.
327 However, extensions hosted on the Chrome Web Store are updated
328 via the Chrome update mechanism which developers do not control.
329 Extension developers should be careful about updating extensions
330 that have a dependency on the native binary
331 (for example, legacy extensions using <a href="npapi">NPAPI</a>).
334 <p><b>What if the user uninstalls the extension?</b> </p>
335 <p>If the user uninstalls the extension through the UI, it will no
336 longer be installed or updated on each startup. In other words, the
337 external extension is blacklisted. </p>
339 <p><b>How do I get off the blacklist?</b> </p>
340 <p>If the user uninstalls your extension, you should respect that
341 decision. However, if you (the developer) accidentally uninstalled
342 your extension through the UI,
343 you can remove the blacklist tag
344 by installing the extension normally
345 through the UI, and then uninstalling it. </p>