Netlify Docs
Ask Netlify

Contact

Configure & deploy site /Static routing /

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 or edge 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 function should return any required headers instead. Visit our docs on edge functions to learn how to configure cache-control headers for edge functions.
  • 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.
  • You can set most 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

      Setting cookies across subdomains only works for custom domains

      netlify.app is listed in the Mozilla Foundation’s Public Suffix List, which prevents setting cookies across subdomains. You can only set a cookie for all subdomains if your site uses a custom domain instead of yoursitename.netlify.app.

# 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.
  • Header field names are case insensitive.
  • Paths can contain wildcards and placeholders.

Here is an example of a _headers file with two URL paths:

# a path:
/templates/index.html
  # headers for that path:
  X-Frame-Options: DENY
# another path:
/templates/index2.html
  # headers for that path:
  X-Frame-Options: SAMEORIGIN

Here’s an example of setting the X-Frame-Options header for all pages on your site:

/*
  X-Frame-Options: DENY

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.
  • Paths can contain wildcards and placeholders.

Here’s an example:

[[headers]]
  for = "/*"
  [headers.values]
    X-Frame-Options = "DENY"

# Wildcards and placeholders in paths

Whether you declare headers in a dedicated _headers file or using the [[headers]] section of netlify.toml, you can take advantage of wildcards and placeholders in URL path segments:

  • Wildcards (*) can be used at any place inside of a path segment to match any character.

  • Placeholders (:placeholders) can only be used at the start of a path segment to match any character except /.

  • Wildcards and placeholders cannot be within the same path segment.

    For example, /templates/:placeholder* won’t work as the wildcard is considered part of the placeholder name. /templates/*:placeholder won’t work as the placeholder needs to be at the beginning of the path segment, right after the /.

Note that Netlify processes wildcards and placeholders in redirects differently than those used in headers. Learn more about the options and limitations for wildcards in splats and placeholders in the redirect options doc.

# 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 is available on Core Pro and Enterprise plans.

You can configure Netlify to provide basic authentication headers on paths you want to hide behind a password.

Visit the basic authentication page for more information.

←