namecheap-python 2.1.0

A friendly Python SDK for Namecheap API

Namecheap Python SDK

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

🚀 Features

[!NOTE] New in v1.6.0: IDN & emoji domain support — pass 🧊.to or café.com directly, punycode handled automatically.

• 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
• 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
❯ namecheap-cli domain check myawesome.com coolstartup.io
                Domain Availability
┏━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┓
┃ Domain         ┃ Available    ┃ Price (USD/year) ┃
┡━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━┩
│ myawesome.com  │ ❌ Taken     │ -                │
│ coolstartup.io │ ✅ Available │ $34.98           │
└────────────────┴──────────────┴──────────────────┘

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

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 - Complete CLI reference
• 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=false          # use production API

.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=False              # Production mode
)

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")

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="[e-mail]"),
    EmailForward(mailbox="support", forward_to="[e-mail]"),
])

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", "[e-mail]")

# 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="[e-mail]"
)

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.

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

API	Status	Methods
namecheap.domains.*	✅ Done	check, list, getInfo, getContacts, getTldList, register, renew, setContacts, lock/unlock
namecheap.domains.dns.*	✅ Done	getHosts, setHosts (builder pattern), add, delete, export, getList, setCustom, setDefault, getEmailForwarding, setEmailForwarding
namecheap.whoisguard.*	✅ Done	getList, enable, disable, renew, changeEmailAddress
namecheap.users.*	⚠️ Partial	getBalances, getPricing. Remaining methods are account management (changePassword, update, create, login, resetPassword) — only useful if building a reseller platform
namecheap.users.address.*	🚧 Planned	Saved address book for domains.register() — store contacts once, reuse by ID instead of passing full contact info every time
namecheap.ssl.*	🚧 Planned	Full SSL certificate lifecycle — purchase, activate with CSR, renew, revoke, reissue. Complex multi-step workflows with approval emails
namecheap.domains.transfer.*	🚧 Planned	Transfer domains into Namecheap programmatically — initiate, track status, retry
namecheap.domains.ns.*	🚧 Planned	Glue records — only needed if you run your own nameservers and need to register them with the registry
namecheap.domains.*	🚧 Planned	reactivate — restore expired domains within the redemption grace period

🤖 Claude Code Integration

The CLI works in Claude Code today — Claude can call namecheap-cli commands via Bash tool calls. A dedicated Claude Code skill is planned that will teach Claude the available commands, flag destructive operations for confirmation, and encode common workflows (GitHub Pages setup, Vercel nameservers, Cloudflare migration).

The goal: tell Claude "set up mycoolproject.dev for Vercel" and it handles registration, DNS, and privacy 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