---
id: pyats-topology
version: "26.7"
license: Apache 2.0
license_treatment: permissive
maintenance: active
---

# pyats.topology — pyATS Topology: Topology Objects and Testbed YAMLs

License: permissive · Maintenance: active · Downloads: 295.7K/mo

## What it is and what it does

pyats.topology is the network modeling layer of the pyATS testing framework, a Cisco-developed end-to-end testing ecosystem. It provides object-oriented abstractions for testbeds, devices, interfaces, links, and segments—the core entities in network test environments. Topology definitions are typically loaded from YAML files, where devices, interfaces, and segments are declared; the package then exposes these as Python objects that test code can traverse and query (e.g., device.links, testbed.segments).

The package is designed as a building block within the larger pyATS ecosystem, which emphasizes data-driven, reusable, and scalable test suites. It depends on pyyaml for file parsing, yamllint for validation, and other pyats submodules (datastructures, connections, utils) for integration with the broader framework. It supports Python 3.8 through 3.14 on Linux and macOS, with no Windows support.

Use it for:

- Load and programmatically access network testbed topology from YAML files in automated test scripts.
- Query device interfaces, links, and segments to build dynamic test scenarios based on network structure.
- Integrate topology models with pyATS test cases to enable data-driven network testing workflows.
- Define multi-device network segments (e.g., QINQ) in YAML and reference them from interface configurations.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Models network testbeds, devices, interfaces, links and segments as Python objects, with support for YAML-based topology definitions.

Yes, if you are building test automation within the pyATS ecosystem or need to model and traverse network testbed topology in Python. The package is actively maintained, has no known vulnerabilities, and carries a permissive license. Medium install friction is acceptable for a specialized testing framework. Not recommended if you need Windows support or are not already committed to the pyATS testing model.

## Install

pip install pyats-topology
uv add pyats-topology
poetry add pyats-topology

## Installing pyats.topology

Before you install: Active maintenance with a release 7 days ago. Medium install friction due to 5 runtime dependencies (pyyaml, yamllint, pyats.datastructures, pyats.connections, pyats.utils) and binary wheels for Python 3.10–3.14 across macOS and Linux platforms.

License in practice: Apache 2.0 permissive license allows commercial and private use with minimal restrictions.

Quickstart:

pip install pyats.topology

from pyats.topology import Testbed

testbed = Testbed.load('topology.yaml')
devices = testbed.devices
links = testbed.links

Requires Python 3.8 or later; Linux and macOS only (Windows not supported).

Verify before relying:

- Whether the package is suitable for dynamic topology updates after initial load.
- Performance characteristics when modeling large testbeds with hundreds of devices.
- Extent of YAML schema validation and error reporting for malformed topology files.

## Package facts

- License: Apache 2.0 (permissive)
- Python support: supports_current
- Install friction: medium
- Maintenance: active
- Downloads: 295.7K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

network topology modeling, testbed device management, network interface abstraction, YAML testbed configuration, network segment and link modeling, network-testing, testbed-automation, cisco-pyats

[View on SkillFed](https://skillfed.io/packages/pyats-topology) · [View on PyPI](https://pypi.org/project/pyats-topology/)