Namecheap Python SDK

A modern, friendly Python SDK for the Namecheap API with comprehensive CLI and TUI tools.

🚀 Features

• Modern Python SDK with full type hints and Pydantic models
• CLI Tool for managing domains and DNS from the terminal
• TUI Application for visual DNS record management
• Smart DNS Builder with fluent interface for record management
• Auto-configuration from environment variables
• Helpful error messages with troubleshooting guidance
• IDN & emoji domain support — pass 🧊.to or café.com directly, punycode handled automatically, and results come back readable instead of as xn--3u9h.to
• Comprehensive logging with beautiful colored output
• Sandbox support for safe testing

🎯 Quick Start

Requires Python 3.12 or higher

namecheap-python: Core Python SDK Library

# Add as a dependency to your project
uv add namecheap-python

from namecheap import Namecheap

# Initialize (auto-loads from environment)
nc = Namecheap()

# Check domain availability
domains = nc.domains.check("example.com", "coolstartup.io")
for domain in domains:
    if domain.available:
        print(f"✅ {domain.domain} is available!")

# List your domains
my_domains = nc.domains.list()
for domain in my_domains:
    print(f"{domain.name} expires on {domain.expires}")

# Manage DNS with the builder
nc.dns.set("example.com",
    nc.dns.builder()
    .a("@", "192.0.2.1")
    .a("www", "192.0.2.1")
    .mx("@", "mail.example.com", priority=10)
    .txt("@", "v=spf1 include:_spf.google.com ~all")
)

namecheap-cli: CLI tool

It was meant as a proof of concept to showcase namecheap-python, but it is a tool that I use

# List domains with beautiful table output

# Run it without install with:
uvx --from 'namecheap-python[cli]' namecheap-cli domain list

# Or install it permanently with:
uv tool install --python 3.12 'namecheap-python[cli]'

# Then run
namecheap-cli domain list

                    Domains (4 total)
┏━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━┓
┃ Domain            ┃ Status ┃ Expires    ┃ Auto-Renew ┃ Locked ┃
┡━━━━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━┩
│ example.com       │ Active │ 2025-10-21 │ ✓          │        │
│ coolsite.io       │ Active │ 2026-05-25 │ ✓          │        │
│ myproject.dev     │ Active │ 2026-05-30 │ ✓          │        │
│ awesome.site      │ Active │ 2026-03-20 │ ✓          │        │
└───────────────────┴────────┴────────────┴────────────┴────────┘

Configure it before first use:

# Interactive setup
namecheap-cli config init

# Creates config file at:
# - Linux/macOS: $XDG_CONFIG_HOME/namecheap/config.yaml (or ~/.config/namecheap/config.yaml)
# - Windows: %APPDATA%\namecheap\config.yaml

Check domain availability and pricing:

# Check domain availability — promo and regular price, so renewals never surprise you
❯ namecheap-cli domain check myawesome.com coolstartup.live
                     Domain Availability
┏━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┓
┃ Domain           ┃ Available    ┃ 1st Year ┃ Regular (USD/yr) ┃
┡━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━┩
│ myawesome.com    │ ❌ Taken     │ -        │ -                │
│ coolstartup.live │ ✅ Available │ $2.98    │ $34.48           │
└──────────────────┴──────────────┴──────────┴──────────────────┘

💡 Suggestions for taken domains:
  • myawesome.com → myawesome.net, myawesome.io, getmyawesome.com

Register a domain (charges your Namecheap account balance, after an explicit confirmation):

❯ namecheap-cli domain register coolstartup.live --contacts-from example.com

Registering coolstartup.live

Years: 1
Price: $2.98 first year (regular $34.48/yr)
Renews at: $39.48/yr
Total: $2.98
Privacy: ✓ free WhoisGuard
Contact: John Doe <john@example.com> (from example.com)
Balance: 68.98 USD available

Register coolstartup.live for $2.98? [y/n] (n): y
✅ Registered coolstartup.live!

--contacts-from copies the registrant contact from a domain you already own; without it the CLI prompts interactively. Auto-renew has no API switch — enable it in the Namecheap dashboard afterwards if you want it.

Manage DNS records:

In this example I'll set up GitHub Pages for my domain tdo.garden

# First, check current DNS records (before setup)
namecheap-cli dns list tdo.garden

# Initial state (Namecheap default parking page):
                         DNS Records for tdo.garden (2 total)
┏━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━┓
┃ Type     ┃ Name                 ┃ Value                      ┃ TTL      ┃ Priority ┃
┡━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━┩
│ CNAME    │ www                  │ parkingpage.namecheap.com. │ 1800     │ 10       │
│ URL      │ @                    │ http://www.tdo.garden/     │ 1800     │ 10       │
└──────────┴──────────────────────┴────────────────────────────┴──────────┴──────────┘

# Add GitHub Pages A records for apex domain
❯ namecheap-cli dns add tdo.garden A @ 185.199.108.153
Adding A record to tdo.garden...
✅ Added A record successfully!

❯ namecheap-cli dns add tdo.garden A @ 185.199.109.153
Adding A record to tdo.garden...
✅ Added A record successfully!

❯ namecheap-cli dns add tdo.garden A @ 185.199.110.153
Adding A record to tdo.garden...
✅ Added A record successfully!

❯ namecheap-cli dns add tdo.garden A @ 185.199.111.153
Adding A record to tdo.garden...
✅ Added A record successfully!

# Add CNAME for www subdomain
❯ namecheap-cli dns add tdo.garden CNAME www adriangalilea.github.io
Adding CNAME record to tdo.garden...
✅ Added CNAME record successfully!

# Verify the setup
❯ namecheap-cli dns list tdo.garden

# Final state with GitHub Pages + old records still present that you may want to remove:
```bash
                         DNS Records for tdo.garden (7 total)
┏━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━┓
┃ Type     ┃ Name                 ┃ Value                      ┃ TTL      ┃ Priority ┃
┡━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━┩
│ A        │ @                    │ 185.199.108.153            │ 1800     │ 10       │
│ A        │ @                    │ 185.199.109.153            │ 1800     │ 10       │
│ A        │ @                    │ 185.199.110.153            │ 1800     │ 10       │
│ A        │ @                    │ 185.199.111.153            │ 1800     │ 10       │
│ CNAME    │ www                  │ parkingpage.namecheap.com. │ 1800     │ 10       │
│ CNAME    │ www                  │ adriangalilea.github.io.   │ 1800     │ 10       │
│ URL      │ @                    │ http://www.tdo.garden/     │ 1800     │ 10       │
└──────────┴──────────────────────┴────────────────────────────┴──────────┴──────────┘

Check account balance:

❯ namecheap-cli account balance
          Account Balance
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━┓
┃ Field               ┃    Amount ┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━┩
│ Available Balance   │  0.00 USD │
│ Account Balance     │  0.00 USD │
│ Earned Amount       │  0.00 USD │
│ Withdrawable        │  0.00 USD │
│ Auto-Renew Required │ 20.16 USD │
└─────────────────────┴───────────┘

Get detailed domain info:

❯ namecheap-cli domain info self.fm

Domain Information: self.fm

Status: Ok
Owner: adriangalilea
Created: 07/15/2023
Expires: 07/15/2026
Premium: No
WHOIS Guard: ✓ Enabled
DNS Provider: CUSTOM

You can also export DNS records:

namecheap-cli dns export example.com --format yaml

namecheap-dns-tui: TUI for DNS management

# Launch interactive DNS manager
namecheap-dns-tui

Install both the CLI and TUI

uv tool install --python 3.12 'namecheap-python[all]'

📖 Documentation

• Examples Overview - Quick examples for all tools
• CLI Documentation - Usage guide, safety rules, and workflows (doubles as the Claude Code skill)
• CLI Command Reference - Every command and flag, generated from the CLI itself
• TUI Documentation - TUI features and usage
• SDK Quickstart - Python code examples

⚙️ Configuration

Environment Variables

Set environment variables in your shell:

# Required
NAMECHEAP_API_KEY=your-api-key
NAMECHEAP_USERNAME=your-username

# Optional
NAMECHEAP_API_USER=api-username  # defaults to USERNAME
NAMECHEAP_CLIENT_IP=auto         # auto-detected if not set
NAMECHEAP_SANDBOX=true           # sandbox API (separate account and key); unset = production

.env files

The CLI auto-loads .env from the current working directory, so cd ~/project && namecheap-cli ... Just Works.

The SDK does not read .env implicitly (libraries shouldn't reach into the filesystem on construction). If your code uses a .env file, load it explicitly:

from dotenv import load_dotenv
load_dotenv()
nc = Namecheap()

# or, equivalently:
nc = Namecheap.from_env_file(".env")

Python Configuration

from namecheap import Namecheap

nc = Namecheap(
    api_key="your-api-key",
    username="your-username",
    api_user="api-username",    # Optional
    client_ip="1.2.3.4",       # Optional, auto-detected
    sandbox=True               # Optional: the sandbox API; production by default
)

Static IP via proxy

Namecheap's API requires whitelisting your client IP — painful when your home IP rotates or your CI runners get random IPs. Instead of re-whitelisting forever, route API calls through any box you control with a static IP (a $5 VPS works).

The SDK uses httpx, which honors the standard proxy environment variables out of the box. For SOCKS proxies, install the socks extra:

uv add 'namecheap-python[socks]'

Then tunnel through your static-IP box and point the proxy env var at it:

# SOCKS tunnel over SSH — no server setup needed
ssh -f -N -D 1080 your-vps

ALL_PROXY=socks5://127.0.0.1:1080 namecheap-cli domain list

Whitelist the VPS IP once in Namecheap (Profile → Tools → API Access) and set NAMECHEAP_CLIENT_IP to it. Now API calls work from anywhere — home, laptop on hotel WiFi, CI — with zero whitelist churn. HTTP proxies work too via HTTPS_PROXY=http://... (no extra needed).

🔧 Advanced SDK Usage

DNS Builder Pattern

The DNS builder provides a fluent interface for managing records:

# Build complex DNS configurations
nc.dns.set("example.com",
    nc.dns.builder()
    # A records
    .a("@", "192.0.2.1")
    .a("www", "192.0.2.1")
    .a("blog", "192.0.2.2")

    # AAAA records
    .aaaa("@", "2001:db8::1")
    .aaaa("www", "2001:db8::1")

    # MX records
    .mx("@", "mail.example.com", priority=10)
    .mx("@", "mail2.example.com", priority=20)

    # TXT records
    .txt("@", "v=spf1 include:_spf.google.com ~all")
    .txt("_dmarc", "v=DMARC1; p=none;")

    # CNAME records
    .cname("blog", "myblog.wordpress.com")
    .cname("shop", "myshop.shopify.com")

    # URL redirects
    .url("old", "https://new-site.com", redirect_type="301")
)

Note on TTL: The default TTL is 1799 seconds, which displays as "Automatic" in the Namecheap web interface. This is an undocumented Namecheap API behavior. You can specify custom TTL values (60-86400 seconds) in any DNS method.

IDN & Emoji Domain Support

# Emoji domains work everywhere
ns = nc.dns.get_nameservers("🧊.to")
info = nc.domains.get_info("🧊.to")
nc.dns.set_custom_nameservers("🧊.to", ["ns1.cloudflare.com", "ns2.cloudflare.com"])

# So do IDN domains
nc.domains.check("café.com", "München.de")

Namecheap stores and returns punycode, so that stays the canonical identity on every model. The Unicode form is derived alongside it:

d = nc.domains.list()[0]
d.name          # 'xn--3u9h.to'  — what the registry holds, what you pass to dig
d.unicode_name  # '🧊.to'        — what you show a human

# Same pairing on the other models: DomainCheck.unicode_domain, DomainInfo.unicode_domain

The CLI renders the Unicode form in tables and carries both in -o json (domain and unicode). domain check additionally shows the punycode in parentheses, since that is the only place a homograph (аpple.com with a Cyrillic а) becomes visible.

Nameserver Management

# Check current nameservers
ns = nc.dns.get_nameservers("example.com")
print(ns.nameservers)  # ['dns1.registrar-servers.com', 'dns2.registrar-servers.com']
print(ns.is_default)   # True

# Switch to custom nameservers (e.g., Cloudflare, Route 53)
nc.dns.set_custom_nameservers("example.com", [
    "ns1.cloudflare.com",
    "ns2.cloudflare.com",
])

# Reset back to Namecheap BasicDNS
nc.dns.set_default_nameservers("example.com")

Domain Info

info = nc.domains.get_info("example.com")
print(info.status)              # 'Ok'
print(info.whoisguard_enabled)  # True
print(info.dns_provider)        # 'CUSTOM'
print(info.created)             # '07/15/2023'
print(info.expires)             # '07/15/2026'

Account Balance

bal = nc.users.get_balances()
print(f"{bal.available_balance} {bal.currency}")  # '4932.96 USD'
print(bal.funds_required_for_auto_renew)          # Decimal('20.16')

Pricing

# Get registration pricing for a specific TLD
pricing = nc.users.get_pricing("DOMAIN", action="REGISTER", product_name="com")
for p in pricing["REGISTER"]["com"]:
    print(f"{p.duration} year: ${p.your_price} (regular: ${p.regular_price})")

# Get all domain pricing (large response — cache it)
all_pricing = nc.users.get_pricing("DOMAIN")

Email Forwarding

# Read
rules = nc.dns.get_email_forwarding("example.com")
for r in rules:
    print(f"{r.mailbox} -> {r.forward_to}")

# Write (replaces all existing rules)
nc.dns.set_email_forwarding("example.com", [
    EmailForward(mailbox="info", forward_to="me@gmail.com"),
    EmailForward(mailbox="support", forward_to="help@gmail.com"),
])

# Remove every rule
nc.dns.clear_email_forwarding("example.com")

For Sale (RFC 10023)

RFC 10023 lets a domain's holder say in DNS that it is for sale: TXT records at _for-sale.<domain>, each v=FORSALE1; plus one tag (furi= contact URI, fval= asking price, ftxt= text, fcod= a code for cooperating parties).

from namecheap import for_sale, for_sale_many

# Read: plain DNS, works for any domain, needs no credentials
sale = for_sale("example.com")   # None when not for sale
if sale:
    print(sale.furi, [str(p) for p in sale.fval], sale.ftxt)

for_sale_many(["a.com", "b.net"])  # parallel; a failed lookup comes back as its exception

# Write: your domains on Namecheap BasicDNS. Replaces only the _for-sale
# records and returns the ones it replaced.
nc.dns.set_for_sale("example.com", furi=["mailto:sales@example.com"])
nc.dns.clear_for_sale("example.com")  # absence is the only "not for sale"

Reading follows the RFC's rules: the version tag alone means "for sale", even with empty or invalid content (kept in sale.invalid); strings without it count only as sale.notes next to a valid record; control and bidirectional-override characters come back as �. A lookup that fails (timeout, SERVFAIL) raises, since it says nothing either way. Writing validates first: one pair per record, 255 octets, a well-formed furi/fval, no duplicates, TTL at most 3600.

Domain Contacts

contacts = nc.domains.get_contacts("example.com")
print(f"{contacts.registrant.first_name} {contacts.registrant.last_name}")
print(contacts.registrant.email)

TLD List

tlds = nc.domains.get_tld_list()
print(f"{len(tlds)} TLDs supported")

# Filter to API-registerable TLDs
registerable = [t for t in tlds if t.is_api_registerable]
for t in registerable[:5]:
    print(f".{t.name} ({t.type}) — {t.min_register_years}-{t.max_register_years} years")

Domain Privacy (WhoisGuard)

# List all WhoisGuard subscriptions
entries = nc.whoisguard.get_list()
for e in entries:
    print(f"{e.domain} (ID={e.id}) status={e.status}")

# Enable privacy (resolves WhoisGuard ID from domain name automatically)
nc.whoisguard.enable("example.com", "me@gmail.com")

# Disable privacy
nc.whoisguard.disable("example.com")

# Renew privacy
result = nc.whoisguard.renew("example.com", years=1)
print(f"Charged: {result['charged_amount']}")

# Rotate the masked forwarding email
result = nc.whoisguard.change_email("example.com")
print(f"New: {result['new_email']}")

Domain Management

# Check multiple domains with pricing
results = nc.domains.check(
    "example.com",
    "coolstartup.io",
    "myproject.dev",
    include_pricing=True
)

for domain in results:
    if domain.available:
        print(f"✅ {domain.domain} - ${domain.price}/year")
    else:
        print(f"❌ {domain.domain} is taken")

# List domains with filters
domains = nc.domains.list()
expiring_soon = [d for d in domains if (d.expires - datetime.now()).days < 30]

# Register a domain
from namecheap import Contact

contact = Contact(
    first_name="John",
    last_name="Doe",
    address1="123 Main St",
    city="New York",
    state_province="NY",
    postal_code="10001",
    country="US",
    phone="+1.2125551234",
    email="john@example.com"
)

result = nc.domains.register(
    "mynewdomain.com",
    years=2,
    contact=contact,
    whois_protection=True
)

Error Handling

from namecheap import NamecheapError

try:
    nc.domains.check("example.com")
except NamecheapError as e:
    print(f"Error: {e.message}")
    if e.help:
        print(f"💡 Tip: {e.help}")

⚠️ Namecheap API Quirks

This section documents undocumented or unusual Namecheap API behaviors we've discovered:

No WHOIS lookups or Marketplace data

The Namecheap API only operates on domains in your account. There is no API for:

• WHOIS lookups on arbitrary domains
• Checking if a domain is listed on Namecheap Marketplace
• Aftermarket pricing or availability

domains.check() tells you if a domain is unregistered, not if it's for sale by its owner. Holders who say so in DNS can be found with namecheap.for_sale() (RFC 10023), which namecheap-cli domain check runs for every taken domain.

No billing or invoice API

Verified against production (2026-08): every plausible command (users.getOrders, users.getInvoices, users.getTransactions, users.getBillingHistory, orders.getList, billing.getInvoices) returns error 4 "Parameter Command is Invalid". The only money-adjacent endpoints are users.getBalances, users.getPricing, and the add-funds pair (createaddfundsrequest/getAddFundsStatus, which push money in, not read billing out). Invoice PDFs live in the dashboard (Profile → Billing & Payments → Invoices, matched by the Order ID that domains.create returns), and Namecheap emails a receipt per order, so a mailbox watcher is the automatable path.

ICANN fee charged even when reported as zero

domains.check sometimes returns IcannFee=0 for a TLD that carries the fee, and registration then charges it anyway (~$0.20/yr). Expect the charged amount to exceed the quoted price by that much; the actual charge comes back in the domains.create response (@ChargedAmount).

TTL "Automatic" = 1799 seconds

The Namecheap web interface displays TTL as "Automatic" when the value is exactly 1799 seconds, but shows "30 min" when it's 1800 seconds. This behavior is completely undocumented in their official API documentation.

Their API docs state TTL defaults to 1800 when omitted, but the UI treats 1799 specially. This SDK defaults to 1799 to match the "Automatic" behavior users see in the web interface.

# Both are valid, but display differently in Namecheap UI:
nc.dns.builder().a("www", "192.0.2.1", ttl=1799)  # Shows as "Automatic"
nc.dns.builder().a("www", "192.0.2.1", ttl=1800)  # Shows as "30 min"

📊 API Coverage

🤖 Claude Code Integration

The CLI ships with a Claude Code skill:

namecheap-cli skill install

This writes the skill to ~/.claude/skills/namecheap-cli/: CLI.md wrapped as SKILL.md (commands, safety rules for destructive operations, common workflows like GitHub Pages setup and Cloudflare migration) plus a command reference generated live from the installed CLI, so it always matches your exact version. Re-run after upgrading.

Then tell Claude "set up mycoolproject.dev for GitHub Pages" and it handles DNS without leaving the conversation.

🛠️ Development

See CONTRIBUTING.md for setup and development guidelines.

📝 License

MIT License - see LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. See CONTRIBUTING.md for setup instructions and guidelines.

Contributors

• @huntertur — Rich dependency fix
• @jeffmcadams — Domain serialization round-trip
• @cosmin — Nameserver management
• @jparavisini — Empty-account crash report
• @SAY-5 — Empty-account crash fix