Match patterns

Host permissions and content script matching are based on a set of URLs defined by match patterns. A match pattern is essentially a URL that begins with a permitted scheme (http, https, file, or ftp, and that can contain '*' characters. The special pattern <all_urls> matches any URL that starts with a permitted scheme. Each match pattern has 3 parts:

  • scheme—for example, http or file or *

    Note: Access to file URLs isn't automatic. The user must visit the extensions management page and opt in to file access for each extension that requests it.

  • host—for example, www.google.com or *.google.com or *; if the scheme is file, there is no host part

  • path—for example, /*, /foo*, or /foo/bar. The path must be present in a host permission, but is always treated as /*.

Here's the basic syntax:

&lt;url-pattern&gt; := &lt;scheme&gt;://&lt;host&gt;&lt;path&gt;
&lt;scheme&gt; := '*' | 'http' | 'https' | 'file' | 'ftp' | 'urn'
&lt;host&gt; := '*' | '*.' &lt;any char except '/' and '*'&gt;+
&lt;path&gt; := '/' &lt;any chars&gt;

The meaning of '*' depends on whether it's in the scheme, host, or path part. If the scheme is *, then it matches either http or https, and not file, ftp, or urn. If the host is just *, then it matches any host. If the host is *._hostname_, then it matches the specified host or any of its subdomains. In the path section, each '*' matches 0 or more characters. The following table shows some valid patterns.

PatternWhat it doesExamples of matching URLs
http://*/*Matches any URL that uses the http schemehttp://www.google.com/
http://example.org/foo/bar.html
http://*/foo*Matches any URL that uses the http scheme, on any host, as long as the path starts with /foohttp://example.com/foo/bar.html
http://www.google.com/foo
https://*.google.com/foo*barMatches any URL that uses the https scheme, is on a google.com host (such as www.google.com, docs.google.com, or google.com), as long as the path starts with /foo and ends with barhttps://www.google.com/foo/baz/bar
https://docs.google.com/foobar
http://example.org/foo/bar.htmlMatches the specified URLhttp://example.org/foo/bar.html
file:///foo*Matches any local file whose path starts with /foofile:///foo/bar.html
file:///foo
http://127.0.0.1/*Matches any URL that uses the http scheme and is on the host 127.0.0.1http://127.0.0.1/
http://127.0.0.1/foo/bar.html
*://mail.google.com/*Matches any URL that starts with http://mail.google.com or https://mail.google.com.http://mail.google.com/foo/baz/bar
https://mail.google.com/foobar
urn:*Matches any URL that starts with urn:.urn:uuid:54723bea-c94e-480e-80c8-a69846c3f582
urn:uuid:cfa40aff-07df-45b2-9f95-e023bcf4a6da
<all_urls>Matches any URL that uses a permitted scheme. (See the beginning of this section for the list of permitted schemes.)http://example.org/foo/bar.html
file:///bar/baz.html

Here are some examples of invalid pattern matches:

Bad patternWhy it's bad
http://www.google.comNo path
http://*foo/bar'*' in the host can be followed only by a '.' or '/'
http://foo.*.bar/baz If '*' is in the host, it must be the first character
http:/barMissing scheme separator ("/" should be "//")
foo://*Invalid scheme

Some schemes are not supported in all contexts.