With custom headers, you can make custom adjustments or additions to the default HTTP headers that Netlify serves with your site when a client makes a request.
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 function such as a server-side rendered (SSR) page, 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.
Location- use redirects instead
Set-Cookie- may be overridden by Netlify cookie handling
- When you declare headers in a
_headersfile stored in the publish directory or a Netlify configuration file, the headers are global for all builds and cannot be scoped for specific branches or deploy contexts. However, there is a workaround you can use to set unique headers for each deploy context.
# 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.
- Paths can contain
:placeholdermatches anything except
/, while a
- 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-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
- 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.
_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, 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:
# Custom headers for different branch or deploy contexts
By default, when you declare headers in a
_headers file stored in the publish directory or in a Netlify configuration file (
netlify.toml), the headers are global for all builds and cannot be scoped for specific branches or deploy contexts.
To set custom headers for a specific branch or deploy context:
Remove any global header declarations from
netlify.tomland, if you have one, remove the
_headersfile from the publish directory.
Create a new custom directory to store your deploy context-specific header files, such as
Create header files for each custom configuration you require and store them in the custom directory. While you can use any file name for each custom file, the files must still follow the syntax for headers files outlined above.
netlify.toml, modify the build command for each deploy context that requires headers. Add the following script to the end of the build command:
&& cp path-to-your-header-file path-to-your-publish-dir/_headers
When the build command for the deploy context runs, Netlify will copy the custom header file to a new file named
_headersin the publish directory for use.
For example, if the custom headers folder is
custom-headers and you want to apply a specific header file
_stagingHeaders to your
staging branch deploys, you would add the following to your
# Configuration for branch deploys for the branch named `staging`. # Remember to replace `npm run build` with your site's build command # and replace `dist` with your site's publish directory. [context.staging] command = "npm run build && cp ./custom-headers/_stagingHeaders ./dist/_headers"
Note that in this example, the site uses
npm run build as the build command and
dist as the publish directory. You should replace those with the appropriate values for your site.
# 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.