You can configure custom headers for your Netlify site in two ways:
- Save a plain text file called
_headersto the publish directory of your site. You can find
_headersfile syntax details below.
- Add one or more
headerstables to your Netlify configuration file. This method allows for more structured configuration and additional capabilities, as described in the Netlify configuration file syntax section below.
- 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, 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
:placeholder matches anything except
/, while a
* matches anything.
Here’s an example of setting the
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
# 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.
_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
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:
# 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.
Did you find this doc useful?
Your feedback helps us improve our docs.