CINXE.COM

<!DOCTYPE html> <html lang="en-US"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width,initial-scale=1"> <title>Custom headers | Netlify Docs</title> <meta name="generator" content="VuePress 1.9.10"> <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Roboto:400,500,700,400italic|Roboto+Mono:400"> <link rel="icon" href="/netlify-icon.svg" type="image/svg+xml"> <link rel="apple-touch-icon" href="/apple-touch-icon.png"> <link rel="icon" href="/favicon-32x32.png" type="image/png" sizes="32x32"> <link rel="icon" href="/favicon-16x16.png" type="image/png" sizes="16x16"> <script>(function (w) { if (!w) return; const darkQuery = w.matchMedia('(prefers-color-scheme: dark)'); const root = document.documentElement; function setTheme(newTheme) { if (newTheme === 'dark' || (newTheme === 'system' && darkQuery.matches)) { root.classList.add('dark-mode'); } else { root.classList.remove('dark-mode'); } w.__theme = newTheme; } w.__setPreferredTheme = function (newTheme) { setTheme(newTheme); try { localStorage.setItem('nf-docs-theme', w.__theme); } catch (err) {} }; // If using system theme, change colors in real time // in response to user settings darkQuery.addEventListener('change', function (event) { if (w.__theme === 'system') { if (event.matches) { root.classList.add('dark-mode'); } else { root.classList.remove('dark-mode'); } } }); let preferredTheme; // Try to get saved theme try { preferredTheme = localStorage.getItem('nf-docs-theme') || 'system'; } catch (err) {} // Initialize preferredTheme setTheme(preferredTheme); })(window);</script> <script src="/rum.js" data-application-id="ededf59a-7705-4933-b2a0-5efa8b35b293" data-client-token="pub1b84fc7c7429f37e025e8160c02da8bb" data-service="docs" data-env="production" defer="true"></script> <meta name="description" content="Define custom headers sent in response to site requests using a _headers file or a netlify.toml file."> <meta property="og:title" content="Custom headers"> <meta property="og:url" content="https://docs.netlify.com/routing/headers/"> <meta property="og:description" content="Define custom headers sent in response to site requests using a _headers file or a netlify.toml file."> <meta property="og:image" content="https://docs.netlify.com/og-image.png"> <meta name="viewport" content="width=device-width, initial-scale=1"> <meta prefix="og: http://ogp.me/ns#" property="og:type" content="article"> <meta prefix="og: http://ogp.me/ns#" property="og:article:author" content="Netlify"> <meta name="google-site-verification" content="G4JqDTXMHpDyWoqIRwgw8PBqg-AncXqtdkHehcOR7kc"> <meta name="slack-app-id" content="A05P27DR8C8"> <link href="https://docs.netlify.com/routing/headers/" rel="canonical" /> <link rel="preload" href="/assets/css/0.styles.2d136594.css" as="style"><link rel="preload" href="/assets/js/app.4a12bea4.js" as="script"><link rel="preload" href="/assets/js/6.f7eff80e.js" as="script"><link rel="preload" href="/assets/js/2.1c921067.js" as="script"><link rel="preload" href="/assets/js/233.0370a1fd.js" as="script"><link rel="preload" href="/assets/js/29.6045b432.js" as="script"> <link rel="stylesheet" href="/assets/css/0.styles.2d136594.css"> </head> <body> <noscript><iframe src="https://www.googletagmanager.com/ns.html?id=GTM-NMKKF2M" height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript> <div id="app" data-server-rendered="true"><div class="theme-container"><header class="navbar-header"><div class="navbar"><div class="navbar__logo-link"><a href="/" class="router-link-active"><span class="visuallyhidden">Netlify Docs</span> <svg width="146" height="40" viewBox="0 0 146 40" fill="none" xmlns="http://www.w3.org/2000/svg" class="netlify-lockup" data-v-4ee6c329><path d="M22.794 39.79V29.687l.21-.21h2.526l.21.21V39.79l-.21.209h-2.527l-.209-.21ZM22.794 10.314V.21l.21-.209h2.526l.21.21v10.104l-.21.21h-2.527l-.209-.21ZM14.1 32.687h-.347l-1.738-1.738v-.347l3.256-3.26 1.84.004.245.242v1.84L14.1 32.686ZM12.015 9.49v-.35l1.738-1.735h.347l3.256 3.256v1.836l-.246.248h-1.839L12.015 9.49ZM.582 18.524h14.316l.21.21v2.53l-.21.209H.582l-.21-.21v-2.53l.21-.209Z" fill="var(--lockup-lines-fill)" data-v-4ee6c329></path> <path d="M29.005 25.265h-2.526l-.21-.21v-5.912c0-1.054-.412-1.869-1.682-1.895-.654-.016-1.4 0-2.199.033l-.12.12v7.651l-.21.21h-2.526l-.21-.21V14.948l.21-.21h5.684a3.998 3.998 0 0 1 3.998 3.999v6.315l-.21.21v.003ZM41.24 20.841l-.21.21H34.5l-.21.209c0 .422.423 1.685 2.108 1.685.631 0 1.263-.21 1.476-.631l.21-.21h2.525l.21.21c-.21 1.263-1.263 3.16-4.424 3.16-3.58 0-5.265-2.526-5.265-5.477 0-2.952 1.685-5.478 5.055-5.478 3.37 0 5.056 2.526 5.056 5.478v.844Zm-3.161-2.107c0-.21-.21-1.686-1.895-1.686s-1.895 1.476-1.895 1.686l.21.21h3.37l.21-.21ZM47.136 22.104c0 .422.21.632.632.632h1.895l.209.209v2.107l-.21.21h-1.894c-1.895 0-3.58-.845-3.58-3.161v-4.634l-.21-.21h-1.475l-.21-.209v-2.107l.21-.21h1.476l.21-.209v-1.894l.209-.21h2.526l.21.21v1.894l.209.21h2.316l.21.21v2.106l-.21.21h-2.316l-.21.21V22.1l.003.003ZM54.93 25.265h-2.525l-.21-.21V10.73l.21-.21h2.526l.21.21v14.322l-.21.21v.003ZM60.618 13.046h-2.526l-.21-.209V10.73l.21-.21h2.526l.21.21v2.107l-.21.21Zm0 12.22h-2.526l-.21-.21V14.944l.21-.21h2.526l.21.21v10.112l-.21.21ZM70.52 10.73v2.107l-.21.21h-1.894c-.422 0-.632.209-.632.631v.844l.21.21H70.1l.21.21v2.106l-.21.21h-2.107l-.21.21v7.581l-.21.21H65.05l-.21-.21v-7.582l-.21-.21h-1.475l-.21-.209v-2.107l.21-.21h1.476l.21-.209v-.844c0-2.317 1.684-3.161 3.58-3.161h1.894l.21.21-.004.003ZM78.311 25.474c-.844 2.108-1.685 3.37-4.633 3.37h-1.054l-.21-.209v-2.107l.21-.21h1.054c1.053 0 1.263-.209 1.475-.84v-.21l-3.37-8.216v-2.108l.21-.21h1.894l.21.21 2.526 7.163h.21l2.525-7.163.21-.21h1.894l.21.21v2.108l-3.37 8.426.01-.004Z" fill="var(--lockup-wordmark-fill)" data-v-4ee6c329></path> <path d="M94.699 25.205V10.707l-.213-.214H92.78l-.213.214v5.117h-.213c-.661-.853-1.706-1.28-2.772-1.28-2.985 0-4.69 2.346-4.69 5.544 0 3.198 1.705 5.543 4.69 5.543 1.13 0 2.132-.469 2.772-1.28h.213l.213.854.213.213h1.493l.213-.213Zm-2.132-5.117c0 2.558-1.066 3.624-2.772 3.624-1.705 0-2.771-1.258-2.771-3.624 0-2.367 1.066-3.625 2.771-3.625 1.706 0 2.772 1.066 2.772 3.625ZM96.614 20.088c0 3.411 1.918 5.543 5.117 5.543 3.198 0 5.117-2.132 5.117-5.543 0-3.412-1.919-5.544-5.117-5.544s-5.117 2.133-5.117 5.544Zm2.132 0c0-2.346 1.066-3.625 2.985-3.625 1.918 0 2.985 1.28 2.985 3.625 0 2.345-1.067 3.624-2.985 3.624-1.92 0-2.985-1.279-2.985-3.624ZM110.26 20.088c0-2.346 1.066-3.625 2.985-3.625 1.705 0 2.345.853 2.558 1.706l.213.213h1.706l.213-.213c-.213-1.919-1.706-3.625-4.69-3.625-3.199 0-5.117 2.133-5.117 5.544 0 3.411 1.918 5.543 5.117 5.543 2.984 0 4.477-1.706 4.69-3.624l-.213-.213h-1.706l-.213.213c-.213.852-.853 1.705-2.558 1.705-1.919 0-2.985-1.279-2.985-3.624ZM127.733 22.433c0-1.919-1.066-2.772-3.199-3.198-2.132-.426-2.984-.64-2.984-1.706 0-.852.852-1.066 1.918-1.066 1.493 0 1.919.64 1.919 1.28l.214.213h1.705l.213-.213c0-2.132-1.705-3.198-4.051-3.198-2.984 0-4.05 1.492-4.05 2.984 0 1.92 1.279 2.772 3.411 3.198 2.132.427 2.772.64 2.772 1.706 0 .853-.64 1.28-2.133 1.28-1.492 0-2.132-.64-2.132-1.706l-.213-.213h-1.705l-.214.213c0 2.345 1.493 3.624 4.264 3.624 2.985 0 4.265-1.492 4.265-3.198Z" fill="var(--lockup-secondary-text-fill)" data-v-4ee6c329></path> <path d="M131.138 18.524h14.316l.209.21v2.53l-.209.209h-14.316l-.21-.21v-2.53l.21-.209Z" fill="var(--lockup-lines-fill)" data-v-4ee6c329></path></svg></a></div> <div class="navbar__actions-wrapper"><form id="search-form" role="search" class="algolia-search-wrapper search-form"><label class="search-form__label"><svg aria-hidden="true" xmlns="http://www.w3.org/2000/svg" width="18" height="18" viewBox="0 0 32 32" class="search-form__label-icon-search"><path d="M20.571 15.143c0-4.411-3.589-8-8-8s-8 3.589-8 8 3.589 8 8 8 8-3.589 8-8zM29.714 30c0 1.25-1.036 2.286-2.286 2.286-0.607 0-1.196-0.25-1.607-0.679l-6.125-6.107c-2.089 1.446-4.589 2.214-7.125 2.214-6.946 0-12.571-5.625-12.571-12.571s5.625-12.571 12.571-12.571 12.571 5.625 12.571 12.571c0 2.536-0.768 5.036-2.214 7.125l6.125 6.125c0.411 0.411 0.661 1 0.661 1.607z" fill="rgba(175, 180, 182, 0.87)"></path></svg> <input id="algolia-search-input" placeholder="Search our docs by topic..." class="search-form__input"></label> <button tabindex="-1" type="reset" class="search-form__label-icon-close"><span class="visuallyhidden">Close search</span> <svg aria-hidden="true" xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 18 18"><g fill="#A3A9AC" transform="scale(-1 1) rotate(45 .571 -12.959)"><rect width="2.333" height="18.667" x="8.164" y=".003"></rect> <polygon points="8.164 .003 10.497 .003 10.497 18.67 8.164 18.67" transform="rotate(-90 9.33 9.336)"></polygon></g></svg></button> <div class="search-form__content-overlay"></div></form> <div class="navbar__right-actions"><a href="/ask-netlify/" aria-label="ask netlify" class="navbar__ask-netlify-link"><span class="navbar__ask-netlify-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 44 44" class="wrapper__icon-ask-netlify"><path fill="currentColor" d="M18.77 23.56a1.8 1.8 0 1 1-3.6 0 1.8 1.8 0 0 1 3.6 0Zm8.26 1.8a1.8 1.8 0 1 0 0-3.6 1.8 1.8 0 0 0 0 3.6Zm-3.86-1.54.03.07v.38l-.03.07-.87 1.77-.12.09h-.32l-.13-.1-.9-1.76-.03-.07v-.38l.03-.07 1-.66h.31l1.03.66Z"></path> <path fill="currentColor" fill-rule="evenodd" d="M22.32 13C28.77 13 34 17.22 34 23.67a6.97 6.97 0 0 1-6.97 6.97H10v-6.97C10 17.22 15.23 13 21.68 13h.64ZM11.55 23.16a5.24 5.24 0 0 1 10.07-2.05h.76l.01-.03a5.24 5.24 0 0 1 10.06 2.08c0 2.65-2.13 5.17-4.53 5.23H16.5a5.24 5.24 0 0 1-4.95-5.23Z" clip-rule="evenodd"></path> <path fill="currentColor" d="m24.47 8.12.07-.16 1.16-.4.15.08.63 1.95-.4.82-.16.06-.82-.4-.63-1.95Zm9.88 3.27.16.06.48 1.13-.07.16-1.9.76-.85-.34-.07-.16.35-.85 1.9-.76ZM30.04 8l.16-.06 1.1.54.05.16-1.14 2.43-.87.3-.15-.08-.3-.86L30.04 8Z" class="ask-netlify-flair"></path></svg></span> <span class="navbar__ask-netlify-label">Ask Netlify</span></a> <div class="user-menu"> <button href="#menu" aria-label="menu" class="menu-trigger is-not-visible-mamabear"><svg viewBox="0 0 31 25" xmlns="http://www.w3.org/2000/svg" class="wrapper__icon-menu"><rect x="0.581177" y="0.71875" width="30" height="4" fill="currentcolor"></rect> <rect x="0.581177" y="10.7188" width="30" height="4" fill="currentcolor"></rect> <rect x="0.581177" y="20.7188" width="30" height="4" fill="currentcolor"></rect></svg></button> <nav aria-label="Netlify navigation" class="navbar__nav is-visible-mamabear navbar__authlinks" data-v-1733a580><div class="navbar__nav-list" data-v-1733a580><a href="https://app.netlify.com/login" rel="noopener noreferrer" class="navbar__nav-link" data-v-1733a580> Log in </a> <a href="https://app.netlify.com/signup" target="self" rel="noopener noreferrer" class="navbar__nav-link signup-button" data-v-1733a580> Sign up </a></div></nav></div></div></div></div></header> <main class="wrapper wrapper--main"><div class="wrapper__sidebar wrapper__navigation"><a class="button button--icon button--close is-not-visible-mamabear"><svg aria-hidden="true" width="24" height="24" viewBox="0 0 16 16" class="icon"><path d="M8,15 C4.13400675,15 1,11.8659932 1,8 C1,4.13400675 4.13400675,1 8,1 C11.8659932,1 15,4.13400675 15,8 C15,11.8659932 11.8659932,15 8,15 Z M10.44352,10.7233105 L10.4528296,10.7326201 L10.7326201,10.4528296 C11.0310632,10.1543865 11.0314986,9.66985171 10.7335912,9.37194437 L9.36507937,8.0034325 L10.7360526,6.63245928 C11.0344957,6.33401613 11.0349311,5.84948135 10.7370237,5.55157401 L10.448426,5.26297627 C10.1505186,4.96506892 9.66598387,4.96550426 9.36754072,5.26394741 L8.00589385,6.62559428 L6.63738198,5.25708241 C6.33947464,4.95917507 5.85493986,4.95961041 5.55649671,5.25805356 L5.26737991,5.54717036 C4.96893676,5.84561351 4.96850142,6.33014829 5.26640876,6.62805563 L6.62561103,7.9872579 L5.25463781,9.35823112 C4.95619466,9.65667427 4.95575932,10.141209 5.25366666,10.4391164 L5.5422644,10.7277141 C5.84017175,11.0256215 6.32470652,11.0251861 6.62314967,10.726743 L7.99412289,9.35576976 L9.36263476,10.7242816 C9.66054211,11.022189 10.1450769,11.0217536 10.44352,10.7233105 Z"></path></svg></a> <div aria-label="Docs" class="sidebar wrapper__sidebar-interior"><nav aria-label="Docs"><div><div class="sidebar__section"><span class="sidebar__section-label">Welcome</span> <ul class="sidebar__links"><li class="sidebar__link-item"><div><a href="/" aria-current="page" class="sidebar__link">Home</a></div></li><li class="sidebar__link-item"><div><a href="/get-started/" class="sidebar__link">Get started</a></div></li><li class="sidebar__link-item"><div><a href="/welcome/add-new-site/" class="sidebar__link">Add new site</a></div></li><li class="sidebar__link-item"><div><a href="/welcome/build-with-ai/" class="sidebar__link">Build with AI</a></div></li><li class="sidebar__link-item"><section tabIndex="-1" class="sidebar__group collapsable is-sub-group"><button tabIndex="-1" class="sidebar__group-heading"> Get help </button>  </section></li></ul></div><div class="sidebar__section"><span class="sidebar__section-label">Platform</span> <ul class="sidebar__links"><li class="sidebar__link-item"><div><a href="/platform/what-is-netlify/" class="sidebar__link">What is Netlify?</a></div></li><li class="sidebar__link-item"><div><a href="/platform/who-is-netlify-for/" class="sidebar__link">Who is Netlify for?</a></div></li><li class="sidebar__link-item"><section tabIndex="-1" class="sidebar__group collapsable is-sub-group"><button tabIndex="-1" class="sidebar__group-heading"> Checklists </button>  </section></li><li class="sidebar__link-item"><section tabIndex="-1" class="sidebar__group collapsable is-sub-group"><button tabIndex="-1" class="sidebar__group-heading"> How we release </button>  </section></li></ul></div><div class="sidebar__section"><span class="sidebar__section-label">Platform primitives</span> <ul class="sidebar__links"><li class="sidebar__link-item"><div><a href="/platform/primitives/" class="sidebar__link">Overview</a></div></li><li class="sidebar__link-item"><section tabIndex="-1" class="sidebar__group collapsable is-sub-group"><button tabIndex="-1" class="sidebar__group-heading"> Functions </button>  </section></li><li class="sidebar__link-item"><section tabIndex="-1" class="sidebar__group collapsable is-sub-group"><button tabIndex="-1" class="sidebar__group-heading"> Edge Functions </button>  </section></li><li class="sidebar__link-item"><section tabIndex="-1" class="sidebar__group collapsable is-sub-group"><button tabIndex="-1" class="sidebar__group-heading"> Image CDN </button>  </section></li><li class="sidebar__link-item"><div><a href="/blobs/overview/" class="sidebar__link">Blobs</a></div></li><li class="sidebar__link-item"><div><a href="/platform/caching/" class="sidebar__link">Caching</a></div></li><li class="sidebar__link-item"><div><a href="/platform/dev-server/" class="sidebar__link">Dev Server</a></div></li><li class="sidebar__link-item"><section tabIndex="-1" class="sidebar__group collapsable is-sub-group"><button tabIndex="-1" class="sidebar__group-heading"> Platform extensions </button>  </section></li></ul></div><div class="sidebar__section"><span class="sidebar__section-label">Frameworks</span> <ul class="sidebar__links"><li class="sidebar__link-item"><div><a href="/frameworks/" class="sidebar__link">Overview</a></div></li><li class="sidebar__link-item"><section tabIndex="-1" class="sidebar__group collapsable is-sub-group"><button tabIndex="-1" class="sidebar__group-heading"> Framework support </button>  </section></li><li class="sidebar__link-item"><div><a href="/frameworks/environment-variables/" class="sidebar__link">Use environment variables with frameworks</a></div></li><li class="sidebar__link-item"><div><a href="/frameworks-api/" class="sidebar__link">Frameworks API</a></div></li></ul></div><div class="sidebar__section"><span class="sidebar__section-label">Developer tools</span> <ul class="sidebar__links"><li class="sidebar__link-item"><section tabIndex="-1" class="sidebar__group collapsable is-sub-group"><button tabIndex="-1" class="sidebar__group-heading"> CLI </button>  </section></li><li class="sidebar__link-item"><section tabIndex="-1" class="sidebar__group collapsable is-sub-group"><button tabIndex="-1" class="sidebar__group-heading"> API </button>  </section></li><li class="sidebar__link-item"><div><a href="/terraform-provider/" class="sidebar__link">Terraform Provider</a></div></li><li class="sidebar__link-item"><div><a href="https://developers.netlify.app/sdk/get-started/introduction/" target="_blank" rel="noopener noreferrer" class="sidebar__link">Netlify SDK</a></div></li><li class="sidebar__link-item"><div><a href="/welcome/command-palette/" class="sidebar__link">Command Palette</a></div></li></ul></div><div class="sidebar__section"><span class="sidebar__section-label">Integrate & extend</span> <ul class="sidebar__links"><li class="sidebar__link-item"><div><a href="/integrations/overview/" class="sidebar__link">Overview</a></div></li><li class="sidebar__link-item"><section tabIndex="-1" class="sidebar__group collapsable is-sub-group"><button tabIndex="-1" class="sidebar__group-heading"> Integrations </button>  </section></li><li class="sidebar__link-item"><section tabIndex="-1" class="sidebar__group collapsable is-sub-group"><button tabIndex="-1" class="sidebar__group-heading"> Build Plugins </button>  </section></li><li class="sidebar__link-item"><div><a href="/slack-app/" class="sidebar__link">Netlify App for Slack</a></div></li><li class="sidebar__link-item"><div><a href="/integrations/extend-netlify/" class="sidebar__link">Extend Netlify</a></div></li></ul></div><div class="sidebar__section"><span class="sidebar__section-label">Configure & deploy site</span> <ul class="sidebar__links"><li class="sidebar__link-item"><section tabIndex="-1" class="sidebar__group collapsable is-sub-group"><button tabIndex="-1" class="sidebar__group-heading"> Git </button>  </section></li><li class="sidebar__link-item"><section tabIndex="-1" class="sidebar__group collapsable is-sub-group"><button tabIndex="-1" class="sidebar__group-heading"> Environment variables </button>  </section></li><li class="sidebar__link-item"><section tabIndex="-1" class="sidebar__group collapsable is-sub-group"><button tabIndex="-1" class="sidebar__group-heading"> Configure builds </button>  </section></li><li class="sidebar__link-item"><section tabIndex="-1" class="sidebar__group collapsable is-sub-group"><button tabIndex="-1" class="sidebar__group-heading"> Site deploys </button>  </section></li><li class="sidebar__link-item"><section tabIndex="-1" class="sidebar__group collapsable is-sub-group"><button tabIndex="-1" class="sidebar__group-heading"> Domains & HTTPS </button>  </section></li><li class="sidebar__link-item"><section tabIndex="-1" class="sidebar__group collapsable is-sub-group"><button aria-expanded="true" tabIndex="-1" class="sidebar__group-heading open"> Static routing </button> <ul class="sidebar__links sidebar__group-items"><li class="sidebar__link-item"><div><a href="/routing/overview/" class="sidebar__link">Overview</a></div></li><li class="sidebar__link-item"><section tabIndex="-1" class="sidebar__group collapsable is-sub-group"><button tabIndex="-1" class="sidebar__group-heading"> Redirects & rewrites </button>  </section></li><li class="sidebar__link-item"><div><a href="/routing/headers/" aria-current="page" class="active sidebar__link">Custom headers</a></div></li></ul> </section></li><li class="sidebar__link-item"><section tabIndex="-1" class="sidebar__group collapsable is-sub-group"><button tabIndex="-1" class="sidebar__group-heading"> Forms </button>  </section></li></ul></div><div class="sidebar__section"><span class="sidebar__section-label">Visual editing</span> <ul class="sidebar__links"><li class="sidebar__link-item"><section tabIndex="-1" class="sidebar__group collapsable is-sub-group"><button tabIndex="-1" class="sidebar__group-heading"> Visual Editor </button>  </section></li><li class="sidebar__link-item"><div><a href="/ai-assisted-publishing/" class="sidebar__link">AI-Assisted Publishing</a></div></li><li class="sidebar__link-item"><div><a href="https://visual-editor-reference.netlify.com/" target="_blank" rel="noopener noreferrer" class="sidebar__link">Visual editor reference</a></div></li></ul></div><div class="sidebar__section"><span class="sidebar__section-label">Manage data</span> <ul class="sidebar__links"><li class="sidebar__link-item"><section tabIndex="-1" class="sidebar__group collapsable is-sub-group"><button tabIndex="-1" class="sidebar__group-heading"> Connect </button>  </section></li></ul></div><div class="sidebar__section"><span class="sidebar__section-label">Site & team management</span> <ul class="sidebar__links"><li class="sidebar__link-item"><section tabIndex="-1" class="sidebar__group collapsable is-sub-group"><button tabIndex="-1" class="sidebar__group-heading"> Accounts & billing </button>  </section></li><li class="sidebar__link-item"><section tabIndex="-1" class="sidebar__group collapsable is-sub-group"><button tabIndex="-1" class="sidebar__group-heading"> Security </button>  </section></li><li class="sidebar__link-item"><section tabIndex="-1" class="sidebar__group collapsable is-sub-group"><button tabIndex="-1" class="sidebar__group-heading"> Monitor sites </button>  </section></li></ul></div></div></nav> <div aria-labelledby="#external-link__header" class="external-links" data-v-bad94b42><p id="external-link__header" class="external-links__header" data-v-bad94b42> Contact </p> <ul class="external-links__list" data-v-bad94b42><li class="external-links__item" data-v-bad94b42><a href="https://answers.netlify.com" target="_blank" rel="noopener noreferrer" class="external-links__link" data-v-bad94b42> Forums </a></li> <li class="external-links__item" data-v-bad94b42><a href="https://www.netlify.com/support/" target="_blank" rel="noopener noreferrer" class="external-links__link" data-v-bad94b42> Contact support </a></li></ul></div> <nav aria-label="Netlify navigation" class="navbar__nav is-visible-mamabear navbar__authlinks is-not-visible-mamabear" data-v-1733a580><div class="navbar__nav-list" data-v-1733a580><a href="https://app.netlify.com/login" rel="noopener noreferrer" class="navbar__nav-link" data-v-1733a580> Log in </a> <a href="https://app.netlify.com/signup" target="self" rel="noopener noreferrer" class="navbar__nav-link signup-button" data-v-1733a580> Sign up </a></div></nav></div></div> <div class="wrapper__sidebar wrapper__toc"><nav aria-label="On this page" data-toc="" class="contents wrapper__sidebar-interior"> <details><summary class="contents__header">On this page</summary> <ol><li><a href="/routing/headers/#limitations" data-slug="limitations">Limitations</a> </li><li><a href="/routing/headers/#syntax-for-the-headers-file" data-slug="syntax-for-the-headers-file">Syntax for the _headers file</a> </li><li><a href="/routing/headers/#syntax-for-the-netlify-configuration-file" data-slug="syntax-for-the-netlify-configuration-file">Syntax for the Netlify configuration file</a> </li><li><a href="/routing/headers/#wildcards-and-placeholders-in-paths" data-slug="wildcards-and-placeholders-in-paths">Wildcards and placeholders in paths</a> </li><li><a href="/routing/headers/#multi-value-headers" data-slug="multi-value-headers">Multi-value headers</a> </li><li><a href="/routing/headers/#custom-headers-for-different-branch-or-deploy-contexts" data-slug="custom-headers-for-different-branch-or-deploy-contexts">Custom headers for different branch or deploy contexts</a> </li><li><a href="/routing/headers/#basic-authentication-headers" data-slug="basic-authentication-headers">Basic authentication headers</a> </li></ol></details></nav></div> <section class="wrapper__content"><header class="content__default"><div class="wrapper__breadcrumbs"><span class="breadcrumb__item"><span>Configure & deploy site</span> <span class="breadcrumb__break">/</span></span><span class="breadcrumb__item"><span>Static routing</span> <span class="breadcrumb__break">/</span></span></div> <h1>Custom headers</h1></header> <div class="content__default"><p>With custom headers, you can make custom adjustments or additions to the default <a href="https://developer.mozilla.org/en-US/docs/Glossary/HTTP_header" target="_blank" rel="noopener noreferrer">HTTP headers</a> that Netlify serves with your site when a client makes a request.</p> <p>You can configure custom headers for your Netlify site in two ways:</p> <ul><li>Save a plain text file called <code>_headers</code> to the <a href="/configure-builds/overview/#definitions">publish directory</a> of your site. You can find <a href="/routing/headers/#syntax-for-the-headers-file"><code>_headers</code> file syntax</a> details below.</li> <li>Add one or more <code>headers</code> tables to your <a href="/configure-builds/file-based-configuration/#headers">Netlify configuration file</a>. This method allows for more structured configuration and additional capabilities, as described in the <a href="/routing/headers/#syntax-for-the-netlify-configuration-file">Netlify configuration file syntax</a> section below.</li></ul> <h2 id="limitations"><a href="#limitations" class="header-anchor">#</a> Limitations</h2> <ul><li>Custom headers apply only to files Netlify serves from our own backing store. If you are <a href="/routing/redirects/rewrites-proxies/#proxy-to-another-service">proxying content to your site</a> or dealing with a URL handled by a <a href="/functions/overview/">function</a> or <a href="/edge-functions/overview/">edge function</a> 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 <a href="/edge-functions/optional-configuration/#response-caching">configure <code>cache-control</code> headers for edge functions</a>.</li> <li>When you declare headers in a <code>_headers</code> 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 <a href="/routing/headers/#custom-headers-for-different-branch-or-deploy-contexts">set unique headers for each deploy context</a>.</li> <li>You can set most <a href="https://en.wikipedia.org/wiki/List_of_HTTP_header_fields#Response_fields" target="_blank" rel="noopener noreferrer">HTTP response fields</a> 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. <ul><li><code>Accept-Ranges</code></li> <li><code>Age</code></li> <li><code>Allow</code></li> <li><code>Alt-Svc</code></li> <li><code>Connection</code></li> <li><code>Content-Encoding</code></li> <li><code>Content-Length</code></li> <li><code>Content-Range</code></li> <li><code>Date</code></li> <li><code>Location</code> - use <a href="/routing/redirects/">redirects</a> instead</li> <li><code>Server</code></li> <li><code>Set-Cookie</code> - may be overridden by Netlify cookie handling</li> <li><code>Trailer</code></li> <li><code>Transfer-Encoding</code></li> <li><code>Upgrade</code><div class="custom-block netlify-warning"><p class="custom-block-title">Setting cookies across subdomains only works for custom domains</p> <p><code>netlify.app</code> is listed in the Mozilla Foundation’s <a href="http://publicsuffix.org/" target="_blank" rel="noopener noreferrer">Public Suffix List</a>, which prevents setting cookies across subdomains. You can only set a cookie for all subdomains if your site uses a <a href="/domains-https/custom-domains/">custom domain</a> instead of <code>yoursitename.netlify.app</code>.</p></div></li></ul></li></ul> <div id="custom-headers" class="legacy-anchor"></div> <h2 id="syntax-for-the-headers-file"><a href="#syntax-for-the-headers-file" class="header-anchor">#</a> Syntax for the <code>_headers</code> file</h2> <p>In a <code>_headers</code> file, you can specify one or several URL paths with their additional headers indented below them:</p> <ul><li>Any line beginning with <code>#</code> will be ignored as a comment.</li> <li>Header field names are case insensitive.</li> <li>Paths can contain <a href="#wildcards-and-placeholders-in-paths">wildcards and placeholders</a>.</li></ul> <p>Here is an example of a <code>_headers</code> file with two URL paths:</p> <div class="language- extra-class"><pre class="language-text"><code># 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 </code></pre></div><p>Here’s an example of setting the <code>X-Frame-Options</code> header for all pages on your site:</p> <div class="language- extra-class"><pre class="language-text"><code>/* X-Frame-Options: DENY </code></pre></div><div class="custom-block netlify-warning"><p class="custom-block-title">Make sure we can access the file</p> <p>If you’re running a build command or site generator, the <code>_headers</code> 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 <code>_</code>. (For Jekyll, this requires <a href="https://jekyllrb.com/docs/configuration/options/" target="_blank" rel="noopener noreferrer">adding an <code>include</code> parameter</a> to <code>_config.yml</code>.)</p></div> <div id="structured-configuration" class="legacy-anchor"></div> <h2 id="syntax-for-the-netlify-configuration-file"><a href="#syntax-for-the-netlify-configuration-file" class="header-anchor">#</a> Syntax for the Netlify configuration file</h2> <p>If you specify your header rules in your <a href="/configure-builds/file-based-configuration/#headers">Netlify configuration file</a>, you can use a more structured configuration format with additional capabilities such as <a href="/routing/redirects/rewrites-proxies/#custom-headers-in-proxy-redirects">headers for proxy redirects</a>:</p> <ul><li>We use <a href="https://toml.io/en/v1.0.0-rc.3#array-of-tables" target="_blank" rel="noopener noreferrer">TOML’s array of tables</a> to specify each individual header rule.</li> <li>The following keywords are available: <ul><li><code>for</code>: the path or URL where the headers will be added.</li> <li><code>values</code>: a map of values to add to the response headers.</li></ul></li> <li>Header field names are case insensitive.</li> <li>Paths can contain <a href="#wildcards-and-placeholders-in-paths">wildcards and placeholders</a>.</li></ul> <p>Here’s an example:</p> <div class="language-toml extra-class"><pre class="language-toml"><code><span class="token punctuation">[</span><span class="token punctuation">[</span><span class="token table class-name">headers</span><span class="token punctuation">]</span><span class="token punctuation">]</span> <span class="token key property">for</span> <span class="token punctuation">=</span> <span class="token string">"/*"</span> <span class="token punctuation">[</span><span class="token table class-name">headers.values</span><span class="token punctuation">]</span> <span class="token key property">X-Frame-Options</span> <span class="token punctuation">=</span> <span class="token string">"DENY"</span> </code></pre></div><h2 id="wildcards-and-placeholders-in-paths"><a href="#wildcards-and-placeholders-in-paths" class="header-anchor">#</a> Wildcards and placeholders in paths</h2> <p>Whether you declare headers in a dedicated <code>_headers</code> file or using the <code>[[headers]]</code> section of <code>netlify.toml</code>, you can take advantage of wildcards and placeholders in URL path segments:</p> <ul><li><p>Wildcards (<code>*</code>) can be used at any place inside of a path segment to match any character.</p></li> <li><p>Placeholders (<code>:placeholders</code>) can only be used at the start of a path segment to match any character except <code>/</code>.</p></li> <li><p>Wildcards and placeholders cannot be within the same path segment.</p> <p>For example, <code>/templates/:placeholder*</code> won’t work as the wildcard is considered part of the placeholder name. <code>/templates/*:placeholder</code> won’t work as the placeholder needs to be at the beginning of the path segment, right after the <code>/</code>.</p></li></ul> <p>Note that Netlify processes wildcards and placeholders in redirects differently than those used in headers. Learn more about the options and limitations for <a href="/routing/redirects/redirect-options/#splats">wildcards in splats</a> and <a href="/routing/redirects/redirect-options/#placeholders">placeholders</a> in the <a href="/routing/redirects/redirect-options/">redirect options</a> doc.</p> <div id="multi-key-header-rules" class="legacy-anchor"></div> <h2 id="multi-value-headers"><a href="#multi-value-headers" class="header-anchor">#</a> Multi-value headers</h2> <p>Some header fields can accept multiple values.</p> <p>In a <code>_headers</code> 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 <a href="https://tools.ietf.org/html/rfc7230#section-3.2" target="_blank" rel="noopener noreferrer">RFC 7230</a>.</p> <p>For example, you can include several <code>cache-control</code> header fields in the file, like this:</p> <div class="language- extra-class"><pre class="language-text"><code>/* cache-control: max-age=0 cache-control: no-cache cache-control: no-store cache-control: must-revalidate </code></pre></div><p>In a <code>netlify.toml</code>, multi-value headers are expressed with multiline strings:</p> <div class="language-toml extra-class"><pre class="language-toml"><code><span class="token punctuation">[</span><span class="token punctuation">[</span><span class="token table class-name">headers</span><span class="token punctuation">]</span><span class="token punctuation">]</span> <span class="token key property">for</span> <span class="token punctuation">=</span> <span class="token string">"/*"</span> <span class="token punctuation">[</span><span class="token table class-name">headers.values</span><span class="token punctuation">]</span> <span class="token key property">cache-control</span> <span class="token punctuation">=</span> <span class="token string">''' max-age=0, no-cache, no-store, must-revalidate'''</span> </code></pre></div><p>In both cases, the values will be collapsed into one header following the HTTP 1.1 specification:</p> <div class="language- extra-class"><pre class="language-text"><code>cache-control: max-age=0,no-cache,no-store,must-revalidate </code></pre></div><h2 id="custom-headers-for-different-branch-or-deploy-contexts"><a href="#custom-headers-for-different-branch-or-deploy-contexts" class="header-anchor">#</a> Custom headers for different branch or deploy contexts</h2> <p>By default, when you declare headers in a <code>_headers</code> file stored in the publish directory or in a Netlify configuration file (<code>netlify.toml</code>), the headers are global for all builds and cannot be scoped for specific branches or <a href="/site-deploys/overview/#deploy-contexts">deploy contexts</a>.</p> <p>To set custom headers for a specific branch or deploy context:</p> <ol><li><p>Remove any global header declarations from <code>netlify.toml</code> and, if you have one, remove the <code>_headers</code> file from the publish directory.</p></li> <li><p>Create a new custom directory to store your deploy context-specific header files, such as <code>/custom-headers</code>.</p></li> <li><p>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 <a href="#syntax-for-the-headers-file">syntax for headers files</a> outlined above.</p></li> <li><p>In <code>netlify.toml</code>, modify the build command for each deploy context that requires headers. Add the following script to the end of the build command: <code>&& cp path-to-your-header-file path-to-your-publish-dir/_headers</code></p> <p>When the build command for the deploy context runs, Netlify will copy the custom header file to a new file named <code>_headers</code> in the publish directory for use.</p></li></ol> <p>For example, if the custom headers folder is <code>custom-headers</code> and you want to apply a specific header file <code>_stagingHeaders</code> to your <code>staging</code> branch deploys, you would add the following to your <code>netlify.toml</code>:</p> <div class="language-toml extra-class"><pre class="language-toml"><code><span class="token comment"># Configuration for branch deploys for the branch named `staging`.</span> <span class="token comment"># Remember to replace `npm run build` with your site's build command</span> <span class="token comment"># and replace `dist` with your site's publish directory.</span> <span class="token punctuation">[</span><span class="token table class-name">context.staging</span><span class="token punctuation">]</span> <span class="token key property">command</span> <span class="token punctuation">=</span> <span class="token string">"npm run build && cp ./custom-headers/_stagingHeaders ./dist/_headers"</span> </code></pre></div><p>Note that in this example, the site uses <code>npm run build</code> as the build command and <code>dist</code> as the publish directory. You should replace those with the appropriate values for your site.</p> <div id="basic-auth" class="legacy-anchor"></div> <h2 id="basic-authentication-headers"><a href="#basic-authentication-headers" class="header-anchor">#</a> Basic authentication headers</h2> <div class="pricing"><p class="pricing-message">This feature is available on <a href='https://www.netlify.com/pricing/?category=developer' target='_blank' class='pricing-link'>Pro</a> and <a href='https://www.netlify.com/pricing/?category=enterprise' target='_blank' class='pricing-link'>Enterprise</a> plans.</p></div> <p>You can configure Netlify to provide <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication#basic_authentication_scheme" target="_blank" rel="noopener noreferrer">basic authentication</a> headers on paths you want to hide behind a password.</p> <p>Visit the <a href="/security/secure-access-to-sites/basic-authentication-with-custom-http-headers/">basic authentication</a> page for more information.</p></div>  <div class="content__default wrapper__last_updated has_page_nav"><time datetime="2024-11-06"> Last updated: November 6, 2024 </time></div> <div class="footer-page-nav"><p class="inner"><span class="prev"> ← <a href="/routing/overview/" class="prev"> Static routing </a></span> </p></div> <div class="feedback"><div class="media"><div class="media__body"><h4 class="media__title"> Did you find this doc useful? </h4>  <p class="media__copy"> Your feedback helps us improve our docs. </p>  </div> <div class="media__figure"><button aria-label="upvote" class="feedback__vote feedback__vote--upvote"><svg xmlns="http://www.w3.org/2000/svg" width="64" height="64" aria-hidden="true"><g fill="none" fill-rule="evenodd"><circle cx="32" cy="32" r="32" fill="none" fill-rule="nonzero"></circle> <g stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2"><path d="M40 29h-7.645l1.473-3.889c.377-.996.042-2.135-.803-2.73-.963-.679-2.263-.427-2.936.569L26 29v9a4 4 0 0 0 4 4h6.517c1.51 0 2.893-.852 3.573-2.203L42 36v-5a2 2 0 0 0-2-2zM22 29v12"></path></g></g></svg></button><button aria-label="downvote" class="feedback__vote feedback__vote--downvote"><svg xmlns="http://www.w3.org/2000/svg" width="64" height="64" aria-hidden="true"><g fill="none" fill-rule="evenodd"><circle cx="32" cy="32" r="32" fill="none" fill-rule="nonzero"></circle> <g stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2"><path d="M23 35h7.645l-1.473 3.889c-.377.996-.042 2.135.803 2.73.963.679 2.263.427 2.936-.569l4.09-6.05v-9a4 4 0 0 0-4-4h-6.518c-1.51 0-2.893.852-3.573 2.202L21 28v5a2 2 0 0 0 2 2zM41 35V23"></path></g></g></svg></button></div></div> <div><form class='form form--floating-labels feedback__form--appear' method='post' name='feedback'><input type="hidden" name="form-name" value="feedback"> <input type="hidden" name="path" value="/routing/headers/"> <input type="hidden" name="vote" value=""> <label class="visuallyhidden"> Do not fill in this field <input name="verification" value=""></label> <div class="form__field"><label><div class="form__label"> What else would you like to tell us about this doc? </div> <textarea name="feedback" class="form__textarea"></textarea></label></div> <div class="btn-group"><button disabled="disabled" class="btn"> Send </button></div></form></div></div> <footer class="footer"><div class="footer-wrapper"><nav aria-label="Footer navigation" class="footer-nav"><ul class="footer__nav"><li class="footer__nav-item"><a href="https://netlify.com/" class="footer__nav-link"> Netlify </a></li> <li class="footer__nav-item"><a href="https://netlify.com/careers/" class="footer__nav-link"> Careers </a></li> <li class="footer__nav-item"><a href="https://netlify.com/blog/" class="footer__nav-link"> Blog </a></li> <li class="footer__nav-item"><a href="https://www.netlify.com/legal/terms-of-use/" class="footer__nav-link"> Terms </a></li> <li class="footer__nav-item"><a href="https://www.netlify.com/privacy/" class="footer__nav-link"> Privacy </a></li></ul></nav> <div class="dark-mode-widget footer__theme-toggle" data-v-0d17f8d5><label for="theme-select" class="visuallyhidden" data-v-0d17f8d5>Select a theme</label> <div class="forms-select-c" data-v-0d17f8d5><div class="theme-toggle-icon" data-v-0d17f8d5><svg width="14" height="14" viewBox="0 0 14 14" fill="none" xmlns="http://www.w3.org/2000/svg" data-v-0d17f8d5><path fill-rule="evenodd" clip-rule="evenodd" d="M14 7C14 10.866 10.866 14 7 14C3.13401 14 0 10.866 0 7C0 3.13401 3.13401 0 7 0C10.866 0 14 3.13401 14 7ZM7 12.2C6.99999 12.2 7.00001 12.2 7 12.2C4.12812 12.2 1.8 9.87188 1.8 7C1.8 4.12812 4.12812 1.8 7 1.8C7.00001 1.8 6.99999 1.8 7 1.8V12.2Z" fill="currentColor"></path></svg>  </div> <select value="system" name="theme-select" id="theme-select" class="forms-input"> <option value="system" data-v-0d17f8d5>System</option><option value="light" data-v-0d17f8d5>Light</option><option value="dark" data-v-0d17f8d5>Dark</option></select> <svg width="21" height="13" viewBox="0 0 21 13" fill="none" xmlns="http://www.w3.org/2000/svg" class="icon-arrow-down forms-select-c-arrow"><path d="M20.7656 1.82812C21.0156 2.10938 21.0156 2.375 20.7656 2.625L10.9219 12.4688C10.6719 12.7188 10.4219 12.7188 10.1719 12.4688L0.328125 2.625C0.078125 2.375 0.078125 2.10938 0.328125 1.82812L1.26562 0.9375C1.51562 0.65625 1.78125 0.65625 2.0625 0.9375L10.5469 9.375L19.0312 0.9375C19.3125 0.65625 19.5781 0.65625 19.8281 0.9375L20.7656 1.82812Z"></path></svg></div></div></div> <p class="footer__copyright">© 2025 Netlify</p></footer></section></main></div><div class="global-ui"></div></div> <script src="/assets/js/app.4a12bea4.js" defer></script><script src="/assets/js/6.f7eff80e.js" defer></script><script src="/assets/js/2.1c921067.js" defer></script><script src="/assets/js/233.0370a1fd.js" defer></script><script src="/assets/js/29.6045b432.js" defer></script> <script src="/netlify-cnm/cnm.js" async defer></script> <script async id="netlify-rum-container" src="/.netlify/scripts/rum" data-netlify-rum-site-id="90a54386-9477-4113-bd6a-b9227b573d00" data-netlify-deploy-branch="main" data-netlify-deploy-context="production" data-netlify-cwv-token="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzaXRlX2lkIjoiOTBhNTQzODYtOTQ3Ny00MTEzLWJkNmEtYjkyMjdiNTczZDAwIiwiYWNjb3VudF9pZCI6IjU4ZGE4ODkzZDY4NjVkMzVjOTJhNzJiOCIsImRlcGxveV9pZCI6IjY3YWY5MjQyM2MyMzIwMDAwOGVkNWViYiIsImlzc3VlciI6Im5mc2VydmVyIn0.ITO2hYKD-bfMx7Aojk4qxSrtteyJXD3ljjojUDrlsYA"></script><script type="text/javascript"> if (window.location.host === "docs.netlify.com") { !function(){var analytics=window.analytics=window.analytics||[];if(!analytics.initialize)if(analytics.invoked)window.console&&console.error&&console.error("Segment snippet included twice.");else{analytics.invoked=!0;analytics.methods=["trackSubmit","trackClick","trackLink","trackForm","pageview","identify","reset","group","track","ready","alias","debug","page","once","off","on","addSourceMiddleware","addIntegrationMiddleware","setAnonymousId","addDestinationMiddleware"];analytics.factory=function(e){return function(){var t=Array.prototype.slice.call(arguments);t.unshift(e);analytics.push(t);return analytics}};for(var e=0;e<analytics.methods.length;e++){var key=analytics.methods[e];analytics[key]=analytics.factory(key)}analytics.load=function(key,e){var t=document.createElement("script");t.type="text/javascript";t.async=!0;t.src="https://cdn.segment.com/analytics.js/v1/" + key + "/analytics.min.js";var n=document.getElementsByTagName("script")[0];n.parentNode.insertBefore(t,n);analytics._loadOptions=e};analytics.SNIPPET_VERSION="4.13.1"; analytics.load("kjz0qkJslzzHMcNGI3GkDb9HDZ6vspYZ"); }}(); } </script></body> </html>