Custom headers

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:

# 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 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.
    • 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
  • When you declare headers in a _headers file 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

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

# 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:

  1. Remove any global header declarations from netlify.toml and, if you have one, remove the _headers file from the publish directory.

  2. Create a new custom directory to store your deploy context-specific header files, such as /custom-headers.

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

  4. In 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 _headers in 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 netlify.toml:

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