A modern, friendly Python SDK for the Namecheap API with comprehensive CLI and TUI tools.
- 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
- Comprehensive logging with beautiful colored output
- Sandbox support for safe testing
Requires Python 3.12 or higher
# Add as a dependency to your project
uv add namecheap-pythonfrom 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")
)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.yamlCheck 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.comManage 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: CUSTOMYou can also export DNS records:
namecheap-cli dns export example.com --format yaml# Launch interactive DNS manager
namecheap-dns-tui
uv tool install --python 3.12 'namecheap-python[all]'- Examples Overview - Quick examples for all tools
- CLI Documentation - Complete CLI reference
- TUI Documentation - TUI features and usage
- SDK Quickstart - Python code examples
Create a .env file or set environment variables:
# 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 APIfrom 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
)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.
# 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")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'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')# 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")# 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"),
])contacts = nc.domains.get_contacts("example.com")
print(f"{contacts.registrant.first_name} {contacts.registrant.last_name}")
print(contacts.registrant.email)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")# 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']}")# 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
)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}")This section documents undocumented or unusual Namecheap API behaviors we've discovered:
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.
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 | 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.* |
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 |
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.
See CONTRIBUTING.md for setup and development guidelines.
MIT License - see LICENSE file for details.
Contributions are welcome! Please feel free to submit a Pull Request. See CONTRIBUTING.md for setup instructions and guidelines.
- @huntertur — Rich dependency fix
- @jeffmcadams — Domain serialization round-trip
- @cosmin — Nameserver management