Last updated April 30, 2024

By default, a Heroku app is available at its Heroku domain, which has the form APPNAME-IDENTIFIER.herokuapp.com. For example, an app named example-app is hosted at example-app-1234567890ab.herokuapp.com. While your app is available at your subdomain, we strongly recommend adding a custom domain to production apps.

Heroku DNS uses DNSSEC to authenticate requests to all herokuapp.com and herokudns.com domains. DNSSEC is a security system that gives DNS servers the ability to verify that the information they receive is reliable.

To make your app available at a non-Heroku domain (for example, www.yourcustomdomain.com), you add a custom domain to it.

You can add custom domains to any Heroku app. Adding domains does not incur extra charges. For security purposes, you must verify your Heroku account to add domains to apps.

Summary of steps

The remainder of this article covers these steps in greater detail:

1. Confirm that you own the custom domain name. You can buy a custom domain name with a domain registration service.
2. Add the custom domain to your app with the heroku domains:add command.
3. Look up the Heroku-supplied DNS target for the custom domain using the heroku domains command.
4. Configure your app’s DNS provider to point to the Heroku-supplied DNS target.
5. Confirm that your app is accessible via the custom domain. There might be a delay while DNS changes propagate.

Add a custom domain with a subdomain

To add a custom domain with a subdomain, use the domains:add Heroku CLI command:

$ heroku domains:add www.example.com -a example-app
Adding www.example.com to ⬢ example-app... done
 ▸    Configure your app's DNS provider to point to the DNS Target
 ▸    whispering-willow-5678.herokudns.com.
 ▸    For help, see https://devcenter.heroku.com/articles/custom-domains

The domain www.example.com has been enqueued for addition
 ▸    Run heroku domains:wait 'www.example.com' to wait for completion

Configuring DNS for subdomains

After you add a domain with the heroku domains:add command, you need to point your DNS provider at the DNS target provided by Heroku. You can view this DNS target with the heroku domains command (see View existing domains for details).

You usually configure a new CNAME record with your DNS provider to point it at Heroku. The following table shows common CNAME record patterns:

Consult your DNS provider’s documentation for specific instructions on creating CNAME records.

You can confirm that your DNS is configured correctly with the host command, assuming your DNS changes have propagated:

$ host www.example.com
www.example.com is an alias for whispering-willow-5678.herokudns.com.
...

Add a custom root domain

Root domains must be added in addition to any subdomains. The process for adding root domains is the same in the Heroku CLI:

$ heroku domains:add example.com -a example-app
Adding example.com to ⬢ example-app... done
 ▸    Configure your app's DNS provider to point to the DNS Target
 ▸    whispering-willow-5678.herokudns.com.
 ▸    For help, see https://devcenter.heroku.com/articles/custom-domains

The domain example.com has been enqueued for addition
 ▸    Run heroku domains:wait 'example.com' to wait for completion

Configuring DNS for root domains

Configuring your DNS provider for a root domain is similar to configuring a DNS provider for a subdomain. However, whereas with subdomains the type of record to configure is always a CNAME, with root domains the type of record depends on the DNS provider:

• ALIAS at DNSimple
• ANAME at DNS Made Easy
• ANAME at easyDNS
• ALIAS at PointDNS
• CNAME at Cloudflare. Also see the document Configure Cloudflare and Heroku over HTTPS.
• ALIAS at Namecheap
• ALIAS at DreamHost

Whichever provider you have, point the ALIAS/ANAME/CNAME entry for your root domain to the DNS Target, just as you would with a CNAME record:

Add a wildcard domain

Wildcard domains allow you to map any and all subdomains to your app with a single record. A common use of a wildcard domain is with applications that use a personalized subdomain for each user or account. You can add a wildcard domain if you own all existing apps already using the same top-level domain (TLD). For example, if an app is already using www.example.com, you must own it to add *.example.com.

Add a wildcard domain to your app as you would with any other domain, but use the * wildcard subdomain notation.

$ heroku domains:add *.example.com -a example-app
Adding *.example.com to ⬢ example-app... done
 ▸    Configure your app's DNS provider to point to the DNS Target
 ▸   encircled-magnolia-9265.herokudns.com.
 ▸    For help, see https://devcenter.heroku.com/articles/custom-domains

The domain *.example.com has been enqueued for addition
 ▸    Run heroku domains:wait '*.example.com' to wait for completion

If one of your apps has a wildcard domain, you can still add specific subdomains of the same top-level domain (TLD) to any of your other apps. Specific subdomains are evaluated before wildcard domains when routing requests.

Configuring DNS for wildcard domains

Use the * wildcard subdomain notation to add a CNAME record to encircled-magnolia-9265.herokudns.com. with your DNS provider.

Remove a custom domain

Remove a domain with domains:remove:

$ heroku domains:remove www.example.com -a example-app
Removing www.example.com from ⬢ example-app... done

If you destroy the app, any custom domains assigned to it will be freed. You can subsequently assign them to other apps.

View existing domains

Use the heroku domains command to view an app’s current Heroku domain, custom domains, and DNS targets:

$ heroku domains -a example-app
=== example Heroku Domain
example.herokuapp.com

=== example Custom Domains
Domain Name      DNS Target
---------------  --------------------------
example.com      hidden-sierra-7936.herokudns.com
www.example.com  whispering-willow-5678.herokudns.com

Rules on adding domains

Any Heroku user can attempt to add any domain to their app. Instead of explicitly verifying domain ownership, Heroku enforces the following rules to ensure that domains aren’t claimed by multiple users or apps:

• A single app can have up to 1,000 custom domains assigned to it.
• A given domain can be added to only a single Heroku app. For example, if you add www.example.com to app example-1, you can’t also add it to app example-2.
• You can add a wildcard domain if you own all existing apps that already use a corresponding subdomain. For example, if an app is already using www.example.com, you must own it in order to add *.example.com.
• You can add a subdomain or apex domain if you own the app that is assigned the corresponding wildcard domain. For example, to add www.example.com or example.com, you must own the app with *.example.com (if such a custom domain exists).
• You can add a subdomain if all applications using wildcard SSL certificates for that domain are owned by the same account. For example, if another account has an app with a *.example.com wildcard SSL certificate uploaded, you can’t add something.example.com to an app on your account.
• wildcard is a reserved Heroku subdomain keyword. For example, wildcard.example.com will fail.

If you’re unable to add a domain that you own, please file a support ticket.

Domain name glossary

• Domain or domain name: full name used to access an app (in words, not with an IP address). For example, www.yourcustomdomain.com
• Subdomain: the www in www.yourcustomdomain.com
• Root domain (or naked, bare, or zone apex domain): the ‘yourcustomdomain.com’ in ‘www.yourcustomdomain.com’
• Wildcard domain: domains that match any subdomain, represented as *.yourcustomdomain.com
• Domain registration service: company that lets you buy and register a custom domain name
• DNS provider: company that maintains the DNS servers that translate a custom domain name to a destination (‘DNS Target’). The fields are often called CNAME, ALIAS, ANAME, or A records. Only the first three work with Heroku apps, as A records require an IP address and Heroku apps do not have stable inbound IP addresses.
• Heroku Domain: Heroku term for default domain given to each app. Has the form APPNAME-IDENTIFIER.herokuapp.com.
• DNS target: Heroku term for the Heroku domain to give to a DNS provider (e.g., in a CNAME record) to be the destination for a custom domain name.