OctoDNS

1.16.0 verified Mon Apr 27 auth: no python

OctoDNS is an infrastructure-as-code tool for managing DNS records across multiple providers. Current version 1.16.0, requires Python >=3.9. Released on a variable cadence, approximately quarterly.

pip install octodns

Common errors

error ModuleNotFoundError: No module named 'octodns.providers' ↓

cause Import path changed in v1.0.0: 'providers' -> 'provider'.

fix

Use 'from octodns.provider.yaml import YamlProvider' (singular).

error Validation error: Zone name must end with a '.' ↓

cause Zone name string missing trailing dot.

fix

Add trailing dot: 'example.com.'

error octodns.manager.Manager: 'config' is not a valid source ↓

cause Missing or misconfigured 'sources' key in manager config or YAML file path is wrong.

fix

Ensure manager config has a 'sources' list and correct file paths.

Warnings

breaking The 'manager' and 'source' directory structure changed in v1.0.0. Existing configs that rely on old import paths or YAML format may break. ↓

fix Update imports to octodns.manager, octodns.provider.yaml, etc. Refer to migration guide.

breaking Provider modules that previously lived in octodns.providers (plural) have been moved to octodns.provider (singular) in v1.0.0. ↓

fix Replace import 'octodns.providers' with 'octodns.provider'.

gotcha Trailing dot required on zone names (e.g., 'example.com.' not 'example.com'). Missing dot causes validation errors. ↓

fix Always include trailing dot on FQDN zone names.

gotcha YAML provider expects file paths relative to the config directory; absolute paths may not work as expected. ↓

fix Use paths relative to the config file, or use absolute paths with care.

Install

pip install octodns[aws,cloudflare,google]

Imports

YamlProvider

wrong

from octodns.yaml import YamlProvider

correct

from octodns.provider.yaml import YamlProvider

Wrong path - YAML provider is in octodns.provider.yaml

Manager

wrong

from octodns import Manager

correct

from octodns.manager import Manager

Manager is not exposed at top-level package

Quickstart

Basic setup for managing a zone with YAML configuration.

from octodns.manager import Manager
from octodns.provider.yaml import YamlProvider
from octodns.source.yaml import YamlSource
from octodns.zone import Zone

# Minimal configuration
config = {
    'manager': {
        'id': 'test',
        'sources': ['config'],
        'providers': {'config': {'class': 'octodns.provider.yaml.YamlProvider'}},
    }
}

zone = Zone('example.com.', [])