Custom headers

You can configure custom headers for your Netlify site in two ways:

Syntax for the _headers file

In a _headers file, you can specify one or several URL paths with their additional headers indented below them. Any line beginning with # will be ignored as a comment.

# a path:
/templates/index.html
  # headers for that path:
  X-Frame-Options: DENY
  X-XSS-Protection: 1; mode=block
# another path:
/templates/index2.html
  # headers for that path:
  X-Frame-Options: SAMEORIGIN

Paths can contain * or :placeholders. A :placeholder matches anything except /, while a * matches anything.

Here's an example of setting the X-Frame-Options and X-XSS-Protection headers for all pages on your site:

/*
  X-Frame-Options: DENY
  X-XSS-Protection: 1; mode=block

Make sure we can access the file

If you're running a build command or site generator, the _headers file should end up in the folder you're deploying. Some generators, like Jekyll, may also require additional configuration to avoid exclusion of files that begin with _. (For Jekyll, this requires adding an include parameter to _config.yml.)

Syntax for the Netlify configuration file

If you specify your header rules in your Netlify configuration file, you can use a more structured configuration format with additional capabilities such as headers for proxy redirects. In a netlify.toml file, we use TOML's array of tables to specify each individual header rule. The following keywords are available:

  • for: The path or URL where the headers will be added.
  • values: A map of values to add to the response headers.

Here's an example:

[[headers]]
  for = "/*"
  [headers.values]
    X-Frame-Options = "DENY"
    X-XSS-Protection = "1; mode=block"

Multi-value headers

Some header fields can accept multiple values.

In a _headers file, you can configure multi-value headers by listing multiple headers with the same field name. Netlify will concatenate the values of those headers into a single header as described in the RFC 7230.

For example, you can include several cache-control header fields in the file, like this:

/*
  cache-control: max-age=0
  cache-control: no-cache
  cache-control: no-store
  cache-control: must-revalidate

In a netlify.toml file, multi-value headers are expressed with multiline strings:

[[headers]]
  for = "/*"
  [headers.values]
	cache-control = '''
	max-age=0,
	no-cache,
	no-store,
	must-revalidate'''

In both cases, the values will be collapsed into one header following the HTTP 1.1 specification:

cache-control: max-age=0,no-cache,no-store,must-revalidate

Basic authentication headers

This feature may not be available on all plans.

You can configure Netlify to provide basic authentication headers on paths you want to hide behind a password.

Visit the password protection page for more information.