Installing pyATS and Genie and setting up the environment is the first step before starting automation with pyATS. In this section, I will demonstrate how to install and configure the required components using a Python virtual environment.
Additionally, I have prepared a Docker image for development purposes that includes all the necessary components covered in this lesson.
pyATS Installation Options
To ensure independence from the operating system and its installed libraries, you can set up a Python virtual environment that includes all the required libraries for your project. This allows you to run your script in an isolated environment. However, this approach can make it difficult to transfer your project to another machine, as you’ll need to manually set up the environment and install dependencies again.
On the other hand, Docker images are highly portable and somewhat OS-independent. With Docker, you can prepare your environment for scripting without needing to perform additional setup, and the containerized environment will work consistently across different machines and operating systems.
| Aspect | Python Virtual Environment | Docker Image |
|---|---|---|
| Independence from OS | Ensures isolation from the OS, but dependent on the host OS's Python version and libraries. | OS-independent; the container works the same across different OSes (Linux, Windows, macOS). |
| Portability | Difficult to transfer between machines; requires manual setup of dependencies on the new machine. | Highly portable; can easily be transferred between Linux and Windows with no setup required. |
| Setup and Configuration | Needs manual setup for each machine, installing dependencies, and configuring the environment. | Pre-configured environment with all dependencies included; just run the container on any machine. |
| Ease of Use Across OSes | Not easy to use across different OSes; might require OS-specific adjustments. | Works the same on any OS (Linux, Windows, macOS) as long as Docker is installed. |
| Environment Consistency | May vary across machines due to OS-specific differences in libraries and Python versions. | Ensures consistency across environments, making it ideal for collaboration and deployment. |
Install pyATS and Genie in a Python Virtual Environment
To set up pyATS using a Python virtual environment, follow these steps:
Create a folder named
pyatsfor your project.Inside the folder, create a virtual environment by running:
python3 -m venv .Activate the virtual environment with:
source bin/activateUpgrade
pipandsetuptoolsto the latest versions using:pip install --upgrade pip setuptoolsInstall the full pyATS package with:
pip install pyats[full]Verify the installation by checking the pyATS version with:
pyats version check
(majid) majid@majid-ubuntu:~/devnet/pyats$ cd /tmp/ (majid) majid@majid-ubuntu:/tmp$ mkdir pyats (majid) majid@majid-ubuntu:/tmp$ cd pyats/ (majid) majid@majid-ubuntu:/tmp/pyats$ python3 -m venv . (majid) majid@majid-ubuntu:/tmp/pyats$ source bin/activate . (pyats) majid@majid-ubuntu:/tmp/pyats$ pip install --upgrade pip setuptools ...
(pyats) majid@majid-ubuntu:/tmp/pyats$ pip install pyats[full] .... (pyats) majid@majid-ubuntu:/tmp/pyats$ pyats version check ... You are currently running pyATS version: 25.1 Python: 3.12.3 [64bit] Package Version ---------------------------- ------- genie 25.1 genie.libs.clean 25.1 genie.libs.conf 25.1 genie.libs.filetransferutils 25.1 genie.libs.health 25.1 genie.libs.ops 25.1 genie.libs.parser 25.1 genie.libs.robot 25.1 genie.libs.sdk 25.1 genie.telemetry 25.1 genie.trafficgen 25.1 pyats 25.1 pyats.aereport 25.1 pyats.aetest 25.1 pyats.async 25.1 pyats.connections 25.1 pyats.contrib 25.1 pyats.datastructures 25.1 pyats.easypy 25.1 pyats.kleenex 25.1 pyats.log 25.1 pyats.reporter 25.1 pyats.results 25.1 pyats.robot 25.1 pyats.tcl 25.1 pyats.topology 25.1 pyats.utils 25.1 rest.connector 25.1 unicon 25.1 unicon.plugins 25.1 yang.connector 25.1 [1]+ Done nohup python addtexttovideo.py (wd: ~/Downloads) (wd now: /tmp/pyats) (pyats) majid@majid-ubuntu:/tmp/pyats$ pyats version check --outdated ... All your packages are up to date! (pyats) majid@majid-ubuntu:/tmp/pyats$ pip install pyats[full] --upgrade #Updates only the specified library or package (pyats) majid@majid-ubuntu:/tmp/pyats$ pyats version update # Updates the entire pyATS framework and all associated packages
(pyats) majid@majid-ubuntu:/tmp/pyats$ pyats -h ... Usage: pyats <command> [options] Commands: clean runs the provided clean file create create scripts and libraries from template develop Puts desired pyATS packages into development mode diff Command to diff two snapshots saved to file or directory dnac Command to learn DNAC features and save to file (Prototype) learn Command to learn device features and save to file logs command enabling log archive viewing in local browser migrate utilities for migrating to future versions of pyATS parse Command to parse show commands run runs the provided script and output corresponding results. secret utilities for working with secret strings. shell enter Python shell, loading a pyATS testbed file and/or pickled data undevelop Removes desired pyATS packages from development mode validate utilities that help to validate input files version commands related to version display and manipulation General Options: -h, --help Show help Run 'pyats <command> --help' for more information on a command. (pyats) majid@majid-ubuntu:/tmp/pyats$
Install pyATS and Genie through docker container
The quicker and easier way to start pyATS scripting without any configuration is by using a pre-built Docker image. This image can be provided by Cisco, created by yourself, or sourced from other contributors. In other words, Python and all necessary libraries are already included in the image, so you only need to load it into a container and run your script.
Cisco has provided an official pyATS Docker image, which includes example scripts. You can pull the image using:
docker pull ciscotestautomation/pyats
For more details, refer to the official documentation: Cisco pyATS Docker Hub.
Additionally, I have created a custom DevNet Docker image, which is not limited to pyATS but includes all essential tools for network automation. This image comes pre-installed with Python, Nornir, and pyATS, allowing you to start scripting immediately. You can pull it using:
docker pull masadpoor/devnet:latest
For more information, visit the documentation: Masadpoor DevNet Docker Hub.
You can run the image inside a Docker container and get shell access using the following command:
docker run -it masadpoor/devnet:latest /bin/bash
If you also want to persist data, you need to mount your local directory inside the Docker container. This allows you to store files and access them even after the container stops.
docker run -it -v $(pwd):/devnet/workspace masadpoor/devnet:latest /bin/bash
After accessing the container shell, you can verify that the pyATS environment is working by cloning the following GitHub repository and running the provided basic example.
git clone https://github.com/CiscoTestAutomation/examples
pyats run job examples/basic/basic_example_job.py
useful links
Finally, here are some useful links to help you during your pyATS learning journey:
📖 Official Documentation
🎓 Beginner Learning Resources
📝 Sample Scripts & Repositories
Here, you can find useful pyATS sample scripts and examples:
📚 Genie Documentation
These resources will help you get started and explore pyATS capabilities more effectively. 🚀