Custom headers

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

# Limitations

  • Custom headers apply only to files Netlify serves from our own backing store. If you are proxying content to your site or dealing with a URL handled by a Netlify Function, custom headers won’t be applied to that content. In those cases, the site being proxied to or the serverless function should return any required headers instead.
  • Custom headers are not compatible with Netlify’s built-in asset optimization. Assets optimized with that feature will not have custom headers applied. You can Disable asset optimization in Site settings > Build & deploy > Post processing > Asset optimization.

# 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:
  # headers for that path:
  X-Frame-Options: DENY
  X-XSS-Protection: 1; mode=block
# another path:
  # 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:

  for = "/*"
    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, multi-value headers are expressed with multiline strings:

  for = "/*"
	cache-control = '''

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.