Custom Domains

Last Updated: 12 March 2015

custom domain dns subdomain

Table of Contents

All apps on Heroku are accessible via their app subdomain. For example, an app named example would be available at To serve traffic on a domain, such as, you need to configure your application with a custom domain.

The way you add a custom domain to your application can vary slightly, depending on the type of domain.

DNS changes can take several minutes to several days to take effect. Lowering your DNS TTL ahead of time can minimize, but not eliminate, this propagation time.

Domain types

There are several domain configurations available to your app:

  • One or more custom subdomains, like
  • A root domain, like or
  • Wildcard domains that match any subdomain, represented as *

A single application can have any number of domains assigned to it, using one or more of the domain configurations described above. The same basic setup process applies for each domain:

  1. Tell Heroku which custom domains are specific to your application
  2. Configure your application’s DNS to point to Heroku

Specific instructions for each configuration are detailed below.

Custom subdomains

For each custom subdomain you want to attach to your app (for example,, use the domains:add command from the Heroku CLI:

$ heroku domains:add
Adding to example... done

See the domain precedence section if you receive the error message is currently in use by another app.

Subdomain DNS

Next, for each subdomain, configure your DNS with a CNAME record pointing the subdomain to your app’s Heroku hostname (shown here resolving to the example app).

The trailing . on the target domain may or may not be required, depending on your DNS provider.

Record Name Target

You can confirm that your DNS is configured correctly by using the host command:

$ host is an alias for

The output of this command varies by Unix flavor, but should indicate that your hostname is either an alias or CNAME of

Root domain

If you intend to use a root domain (for example, or you must add it in addition to any custom subdomains.

$ heroku domains:add
Adding to example... done

Zone apex domains are sometimes called “naked”, “bare” or “root” domains. Zone apex domains (for example,, using conventional DNS A-records are not supported on Heroku. However, there are alternative configurations that allow for root domains while still being resilient in a dynamic runtime environment.

CNAME functionality at the apex

Some DNS hosts provide a way to get CNAME-like functionality at the zone apex using a custom record type. Such records include:

For each provider, the setup is similar: point the ALIAS or ANAME entry for your apex domain to, just as you would with a CNAME record.

Depending on the DNS provider, an empty or @ Name value identifies the zone apex.

Record Name Target
ALIAS or ANAME <empty> or @

If your DNS provider does not support such a record-type, and you are unable to switch to one that does, you will need to use subdomain redirection to send root domain requests to your app on Heroku.

Subdomain redirection

For users without access to a modern DNS configuration, subdomain redirection is a viable alternative. Subdomain redirection results in a 301 permanent redirect to the specified subdomain for all root domain requests.

Almost all DNS providers offer domain redirection services—sometimes also called domain forwarding. However, be aware that, using this method, a secure request to the root domain, e.g.,, will result in an error or warning being displayed to the user or the connection may be refused altogether. If you’re not using SSL, or are only distributing URLs in subdomain SSL form, e.g.,, this error won’t affect you.

Establish a redirect/forward from the root domain to the www subdomain:

Record Name Target
URL or Forward

If not already configured, the www subdomain should then be a CNAME record reference to

Users of AWS’s Route 53 DNS should follow these instructions to establish proper root domain redirection.

Wildcard domains

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, you must own it to add *

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

$ heroku domains:add *
Adding * to example... done

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.

It’s important to make sure your DNS configuration agrees with the custom domains you’ve added to Heroku. In particular, if you have configured your DNS for * to point to, be sure you also run heroku domains:add * Otherwise, a malicious person could add to their Heroku app and receive traffic intended for your application.

Wildcard DNS

Use the * wildcard subdomain notation to add a CNAME record to with your DNS provider.

Record Name Target

After your DNS changes have propagated, you will be able to look up and access any subdomain:

$ host is an alias for

$ curl -I
HTTP/1.1 200 OK

Remove a domain

Remove a domain with domains:remove:

$ heroku domains:remove
Removing from example... done

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

Domain precedence

Any user on Heroku can attempt to add any domain to their app. Instead of explicitly verifying domain ownership, Heroku enforces these rules to ensure that domains claimed by one user aren’t used by other users on different apps:

  • You can only add a domain to one app. For example if is added to app example-1 you can’t also add it to app example-2. One app, however, can have multiple domains assigned.
  • You can add a wildcard domain if you own all existing apps already using a corresponding subdomain. For example if an app is already using you must own it to add *
  • You can add a subdomain or apex domain if you own the app assigned the corresponding wildcard domain. For example to add or you must own the app with *, if such a custom domain exists.

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

The domain

The domain will always remain active, even if you’ve set up a custom domain. If you want users to use the custom domain exclusively, your app should send HTTP status 301 Moved Permanently to tell web browsers to use the custom domain. The Host HTTP request header field will show which domain the user is trying to access; send a redirect if that field is

UTF-8 domain names

Domain names that contain accented, or other non-ASCII, characters should be added using punycode. For instance, the é domain name should be converted to when passed to heroku domains:add:

$ heroku domains:add