Install & Compatibility
Where this runs
tested against v0.37.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 1.495s · 47.7MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 4.2s · import 1.147s · 48MB
47MB installed
● package 47MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Client
✓ from google.cloud import dns
✗ from google.cloud.dns.client import Client
The direct import `from google.cloud.dns.client import Client` was used in older versions of the `google-cloud` meta-package (e.g., prior to 1.0) but is deprecated in favor of `from google.cloud import dns` where `dns.Client` is the recommended instantiation.
This quickstart initializes the Google Cloud DNS client and lists all managed zones within a specified Google Cloud project. It leverages Application Default Credentials (ADC) for authentication, automatically inferring credentials from the environment. For local execution, ensure the `GOOGLE_CLOUD_PROJECT` environment variable is set or replace the placeholder. You'll also need to authenticate with `gcloud auth application-default login`.
import os
from google.cloud import dns
# Your Google Cloud project ID
project_id = os.environ.get('GOOGLE_CLOUD_PROJECT', 'your-project-id')
if not project_id or project_id == 'your-project-id':
print("Please set the 'GOOGLE_CLOUD_PROJECT' environment variable or replace 'your-project-id' in the code.")
exit(1)
# Initialize the DNS client
# The client automatically handles authentication using Application Default Credentials (ADC)
# For local development, ensure you've run 'gcloud auth application-default login'
client = dns.Client(project=project_id)
try:
# List managed zones
print(f"Listing managed zones for project: {project_id}")
zones = client.list_zones()
if not zones:
print("No managed zones found.")
else:
for zone in zones:
print(f" Zone Name: {zone.name}, DNS Name: {zone.dns_name}")
except Exception as e:
print(f"An error occurred: {e}")
Debug
Known issues
breakingPython 2.7 support was dropped in `google-cloud-python` 2.0.0. Current versions require Python 3.9 or newer.fixUpgrade your Python environment to 3.9+ and ensure your `google-cloud-dns` library is updated accordingly. Review the official migration guides for any specific API changes if coming from very old versions.
affects: <2.0.0 (for Python 2.7 users)
gotchaEnsure the Cloud DNS API is enabled in your Google Cloud project. Attempting operations without enabling the API will result in 'attempted action failed' or similar permission errors.fixNavigate to the Google Cloud Console, search for 'Cloud DNS API' in the API Library, and enable it for your project.
affects: All versions
gotchaWhen creating DNS records, be aware of DNS specifications and Cloud DNS limitations, particularly regarding CNAME records. A CNAME record cannot exist at the zone apex (root domain) and cannot coexist with other record types for the same DNS name.fixUse A/AAAA records for the zone apex. For subdomains, ensure CNAMEs do not conflict with other record types. Always include a trailing dot for fully qualified domain names (e.g., 'example.com.') in record data.
affects: All versions
gotchaAuthentication for Google Cloud client libraries, including `google-cloud-dns`, typically relies on Application Default Credentials (ADC). For local development, `gcloud auth application-default login` generates user credentials for client libraries, distinct from `gcloud auth login` which authenticates the CLI itself.fixFor client library authentication in local development, use `gcloud auth application-default login`. In production, configure service accounts or other appropriate ADC mechanisms.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'google.cloud'
The generic `google-cloud` meta-package is deprecated and does not include the specific `google-cloud-dns` client library, or the required specific client library was not installed.
fixInstall the correct client library for Google Cloud DNS: `pip install google-cloud-dns`
Cloud DNS API is not enabled
The Google Cloud DNS API has not been enabled for the Google Cloud project, preventing operations like creating managed zones.
fixEnable the Cloud DNS API in the Google Cloud Console: Navigate to 'APIs & Services' > 'Library', search for 'Cloud DNS API', and click 'Enable'.
googleapi: Error 403: Permission denied
The authenticated service account or user lacks the necessary IAM permissions (e.g., `roles/dns.admin`) to perform the requested operation, such as creating or modifying DNS resources.
fixGrant the appropriate IAM role (e.g., 'DNS Administrator' or `roles/dns.admin`) to the service account or user in the Google Cloud Console.
cnameResourceRecordSetConflict
This error occurs when attempting to create a CNAME record at the zone apex (root domain) or when an A/AAAA record already exists for the same DNS name, which is prohibited by DNS specifications (CNAMEs cannot coexist with other record types at the same name).
fixDo not create CNAME records at the zone apex (e.g., `example.com.`). Instead, use A/AAAA records for the apex and CNAME records for subdomains (e.g., `www.example.com.`). Ensure no other records conflict with a CNAME record for the same name.
SERVFAIL
A generic DNS resolution failure often caused by misconfigured name server delegation at the registrar, incorrect DNSSEC settings (DS record mismatch), firewall rules blocking DNS traffic, or issues with forwarding/peering configurations in private zones.
fixVerify that your domain's name servers at the registrar point to the Cloud DNS name servers. Check DNSSEC configuration for DS record consistency. For private zones, ensure inbound forwarding is enabled, network authorization is correct, and firewall rules allow DNS traffic to the metadata server (169.254.169.254:53).
Upgrade
Version history
0.37.0latest on PyPI · released May 7, 2026
Audit
Dependencies
PythonrequiredRequires Python 3.9 or newer.
google-api-corerequiredCore dependency for Google Cloud client libraries, providing API client common functionality.
google-authrequiredCore dependency for Google Cloud client libraries, handling authentication.