How to Set Up Favicons Across Multiple Domains, Subdomains, and Environments

Overview

A favicon is a small identity asset, but its delivery depends on ordinary web deployment details: the hostname, file path, HTML head, web app manifest, caching layer, and build configuration. A favicon for a subdomain does not automatically need to be different from the parent domain, but it should be an intentional decision. A customer dashboard, documentation site, marketing site, and internal tool may share a brand while using distinct visual markers to help users identify where they are.

Start by deciding which hosts require a favicon and whether each host should use a shared or environment-specific asset. Record that decision in a deployment matrix before changing files. For example:

For asset preparation, use a favicon generator or an established export workflow to create the required PNG, ICO, SVG, and touch-icon files. Keep the source artwork separate from generated files so a rebrand can be repeated consistently. The favicon size and HTML guide can help you choose a practical file set, while the logo-to-favicon workflow covers the design and export decisions.

Checklist by scenario

One brand across several production subdomains

1. List every public hostname, including documentation, support, account, app, and API-adjacent web interfaces.
2. Choose one canonical asset location, such as /assets/icons/, for each application or a shared static host.
3. Use the same approved references in each application unless the subdomain has a deliberate product identity.
4. Confirm that relative paths resolve from every application route, not only from the homepage.
5. Test direct requests to each icon URL from each hostname.

A relative reference such as href="/favicon.ico" is usually easier to maintain than a path tied to a specific route. If assets are served from a shared domain, use a controlled absolute URL and verify that content security, cross-origin behavior, and availability are appropriate for your setup.

Production and staging

1. Create visibly different staging assets, such as a color or letter variant, so screenshots and browser tabs are easier to identify.
2. Store the staging asset in staging configuration rather than editing production HTML manually.
3. Use environment variables or build-time settings for the favicon base path, asset filename, and manifest URL.
4. Inspect the built output before release to ensure production files do not contain staging filenames or hostnames.
5. Open the deployed production page in a clean browser profile and inspect the final HTML.

Environment separation should apply to every identity reference, not just the favicon. Check the manifest, Apple touch icon, Open Graph image, page title, and any application shell that may expose a staging label. A distinct staging favicon is helpful, but it should support—not replace—access controls and other safeguards.

Preview and branch deployments

1. Define a predictable fallback for temporary URLs.
2. Prefer one neutral preview icon over generating a new branded file for every branch.
3. Make sure preview builds do not point to a production-only static path that is unavailable to the preview host.
4. Check whether the deployment platform rewrites asset URLs or changes the application base path.
5. Remove temporary preview references when the build configuration is promoted.

Multiple brands, products, or regional sites

1. Create a small asset inventory with product name, hostname, environment, source file, and approved icon set.
2. Give each product a stable folder or package rather than relying on ambiguous names such as icon-final.png.
3. Keep shared infrastructure separate from brand-specific configuration.
4. Test domain changes and redirects, especially when a product moves between subdomains.
5. Document which icon is intentional when two products share similar marks.

What to double-check

Inspect the complete identity chain rather than checking only whether a tab displays an icon.

• HTML head: Confirm the rel, file path, and type attributes are correct for the files you publish. Avoid adding a long list of redundant references without a reason.
• Manifest: If the application uses a web app manifest, verify its icon paths, purposes, and environment-specific URL configuration. A manifest can provide a separate source of identity from the HTML favicon.
• File availability: Request each icon directly and check the final status, content type, and response body. A successful HTML fallback response is not a valid image.
• Path resolution: Test a deep route, such as /settings/profile, as well as the root page. Relative paths can behave differently when the document is nested.
• Build output: Search compiled HTML, JavaScript configuration, and manifests for old hostnames, staging labels, or deleted filenames.
• CDN and cache: Determine how static assets are cached and how a changed filename or query strategy will be deployed. When an icon seems stuck, use the favicon troubleshooting checklist.
• Visual clarity: Review the icon at small sizes. Product initials, environment labels, and regional symbols can become indistinguishable when reduced.
• Security and compatibility: Treat SVG files as deployed web assets, not merely design files. Review the guidance on SVG favicon security and compatibility before publishing them.

Keep a short deployment record containing the expected icon URL for every host. During an incident or rebrand, this is faster to use than reconstructing the configuration from several repositories.

Common mistakes

Using one hard-coded absolute URL everywhere

A production URL embedded in a shared application can cause staging and preview deployments to display the production icon—or fail when the production host is not reachable from an isolated environment. Make the asset origin configurable or serve the file from each host.

Assuming the root favicon covers every application

A file at the root of one domain is not automatically available on another domain or subdomain. Each host needs a valid reference and a route that serves the asset.

Changing the file but not the cache strategy

Replacing an image while keeping the same URL can make verification confusing. Use a deliberate cache policy and, where appropriate, a versioned filename. Do not rely on repeatedly refreshing one browser tab as proof that all users will see the change.

Letting staging resemble production

A staging favicon that looks identical to production increases the chance of testing the wrong environment or sharing an incorrect screenshot. Use an obvious but restrained distinction, and apply it consistently to the title and other environment markers.

Publishing only one format without testing the target stack

There is no universal need to publish every possible icon format. Choose a compact, well-tested set for your applications and verify it across the browsers, devices, and framework output that matter to your audience. For format decisions, compare the practical trade-offs in the PNG, ICO, and Apple touch icon guide.

When to revisit

Review this setup before each seasonal planning cycle or release window that changes public infrastructure. It should also be revisited when a new subdomain is created, an application moves frameworks, a CDN or hosting provider changes, a regional domain launches, or a product is renamed. Recheck it after a rebrand, a design-system update, a manifest change, or a major browser and platform support review.

A practical recurring review can be completed in four steps:

1. Export the current hostname and environment list from your deployment inventory.
2. Compare it with the favicon deployment matrix and remove retired hosts.
3. Run direct asset requests and inspect the final HTML and manifest for each important host.
4. Record the tested asset URLs, expected visual variants, and any follow-up work in the release notes.

Before creating the next site or subdomain, reuse this checklist rather than copying the nearest existing configuration. A small amount of structure keeps favicon files, HTML references, and environment identity aligned as your web presence grows.