Changing a hosted site’s domain used to be a rebuild in disguise: create the new domain, copy files, move databases, recreate mailboxes, and then delete the old one. Changing an account’s primary domain has been possible through WHM → Modify an Account for years, but addon domains had no equivalent. cPanel & WHM 138, released in July 2026, introduced in-place domain rename for addon domains, so a customer who rebrands or a site that launched on a temporary cpanel.site name can be moved to its real domain with the files, mail and databases left where they are. This guide sets out what the rename does and the steps around it.
Table of Contents
Short answer: Rename a primary domain with whmapi1 modifyacct user=customer DNS=new.example or WHM → Modify an Account; on cPanel 138 and later, rename an addon domain from cPanel → Domains → Manage → Rename or with uapi --user=customer Domains rename_domain domain=old new_domain=new. Files, databases and mailbox contents stay in place, but DNS custom records, the SSL certificate and application-stored URLs such as WordPress site settings must be updated afterwards.
What a rename changes
An in-place rename updates the domain name in cPanel’s user data, rewrites the Apache virtual host, creates a DNS zone for the new name if DNS is local, recreates mail routing and the mail account directories under the new name, and moves the document root only if it was named after the domain. It does not touch database contents, so an application that stores its own URL, WordPress being the obvious case, needs its settings updated separately.
It does not migrate the old DNS zone’s custom records; those must be recreated on the new zone. And it does not carry the SSL certificate across, because a certificate is tied to the name; AutoSSL issues a new one on the next run.
Mail accounts are renamed to the new domain. user@old.example becomes user@new.example with the same mailbox contents, and the old addresses stop working unless the old domain is kept as an alias.
Rename a primary domain
In WHM → Account Functions → Modify an Account, choose the account, change the Primary Domain field, and save. From the shell:
whmapi1 modifyacct user=customer DNS=new.exampleThe change takes a few seconds. WHM reports each subsystem it updated and any it could not, most often a DNS zone that already exists on a cluster peer or a document root that could not be moved because of a custom path. If DNS is hosted elsewhere, the new zone is created locally anyway and can be ignored.
The former primary domain is not automatically kept. If you want mail and web to keep working on the old name during a transition, park it on the account afterwards:
whmapi1 park domain=old.example user=customerRemove it when the customer is ready.
Rename an addon domain (138+)
Log in as the user, or use WHM’s “cPanel” link for the account, and open cPanel → Domains. Each addon domain has a Manage action; on 138 and later that page includes a Rename control. Enter the new domain, confirm the document root behaviour, and submit. The user-level API offers the same:
uapi --user=customer DomainInfo list_domains
uapi --user=customer Domains rename_domain domain=oldaddon.example new_domain=newaddon.exampleIf your build reports that the function is unavailable, check the version and the feature list for the account, since the rename action is exposed through the Domains feature. The result includes the new document root path and a list of anything that needs manual follow-up.
A subdomain of the primary domain cannot be renamed to a domain outside it this way; convert it to an addon domain first, or create the addon domain and move the files.
Follow-up work after any rename
Work through this list for every rename, because these are the pieces the tool cannot do for you.
- DNS: if the new zone is local, add any custom records that existed on the old zone such as third-party MX, verification TXT records or subdomain A records. Compare
whmapi1 dumpzone domain=old.examplewith the new zone. If DNS is hosted externally, point the new domain at the server. - SSL: run
/usr/local/cpanel/bin/autossl_check --user=customeronce DNS resolves. Until then the site serves the account’s fallback certificate and browsers warn. - Mail: republish SPF, DKIM and DMARC for the new domain with WHM → Email Deliverability, and tell the customer their addresses have changed. Mail clients need the new username.
- WordPress: update the site and home URLs with WP Toolkit’s URL change tool or
wp search-replace 'https://old.example' 'https://new.example' --all-tables. Other applications have their own configuration file with the hostname in it. - Cron jobs, scripts and
.htaccessrules that mention the old name. - Old name retention: park the old domain if inbound mail or links must keep working, and add a permanent redirect from it to the new site.
Verify
Confirm the domain is attached, resolving and secured:
uapi --user=customer DomainInfo list_domains
dig +short new.example
curl -sI https://new.example/ | grep -iE 'HTTP|location'
uapi --user=customer Email list_pops | grep new.exampleLog into webmail as one of the renamed mail accounts, browse the site including an admin login, and check that the old domain either redirects or is deliberately gone.
Common pitfall
The most damaging mistake is renaming a domain whose DNS is hosted at a registrar or CDN before the new name’s records point at the server. The rename succeeds, cPanel creates a local zone nobody queries, and the site is unreachable until DNS is fixed elsewhere. Lower the TTL on the new domain a day in advance, prepare the records, and rename in a window where you can flip DNS immediately. The second is forgetting that mail addresses change. Customers with mail clients configured for user@old.example see login failures the moment the rename completes, so warn them first and give them the new settings.
Rename addon domain cPanel at a glance
Official documentation: cPanel & WHM documentation, Linux man pages.
Related guides: Cloudflare in front of cPanel: DNS, proxy mode and real visitor IPs done right · Creating a temporary *.cpanel.site domain and parking your real domain on it later · Is your cPanel server patched? Mapping the 2026 CVEs (41940, 58048, 65643, 67401, 87899) to build numbers.
Frequently asked questions
Does renaming a domain in cPanel keep the email accounts and messages?
Yes. Mail accounts are recreated under the new domain with the same mailbox contents, so user@old.example becomes user@new.example. The old addresses stop receiving mail unless the old domain is parked on the account.
Can I rename an addon domain on cPanel versions before 138?
No. Before 138 only the primary domain could be changed in place through Modify an Account; an addon domain had to be created fresh under the new name and its files, databases and mailboxes moved manually.
Does the SSL certificate move to the renamed domain?
No. A certificate is bound to the old name, so the renamed site serves the fallback certificate until AutoSSL issues a new one. Run /usr/local/cpanel/bin/autossl_check --user=customer once the new domain resolves to the server.