Netlify Docs
Netlify.com Homepage

Contact

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 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.
  • You can set most standard HTTP response fields using custom headers. The following header names are exceptions. Custom headers for these are typically ignored because Netlify’s web servers need to set these headers to work properly.
    • Accept-Ranges
    • Age
    • Allow
    • Alt-Svc
    • Connection
    • Content-Encoding
    • Content-Length
    • Content-Range
    • Date
    • Location - use redirects instead
    • Server
    • Set-Cookie - may be overridden by Netlify cookie handling
    • Trailer
    • Transfer-Encoding
    • Upgrade

# 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.
  • Paths can contain * or :placeholders. A :placeholder matches anything except /, while a * matches anything.
  • Header field names are case insensitive.
# 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

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:

  • 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.
  • Header field names are case insensitive.

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, 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.

←