Installation

This topic describes how to install the pyATS within your system.

Warning

For all internal Cisco engineering users, skip this section, and refer to the engineering internal Wiki for detailed instructions on installing pyATS within Cisco.

pyATS installation process
Type of user	Installation process
Virtual Environment	Check the Requirements. configure-environment. Upgrade and run the package installer for Python (pip): `pip install "pyats[full]"` Verify the installation: `$ pyats version check` Examples Repository. Run the example: `$ pyats run job examples/basic/basic_example_job.py`
Docker	Download the Docker image from https://hub.docker.com/r/ciscotestautomation/pyats/. Start the pyATS container. Run the examples.

Tip

Once you install the pyATS ecosystem, remember to keep your system up to date.

Virtual Environment

pyATS development team recomments you to always develop and run Python scripts with a Python virtual environment. This section describes how to check your Python version, and creating a virtual environment using your available binary.

Python Version

Note

Make sure your system has a supported version of Python installed:

Python 3.7.x
Python 3.8.x
Python 3.9.x
Python 3.10.x

To check your installed version:

$ python --version

Result: The system returns the installed version number:

$ Python 3.7.4

Tip

pyenv a great utility for managing multiple Python versions within your system.

Create Virtual Environment

A Python Virtual Environment is simply a directory (folder). Within this virtual environment, you install the pyATS and pyATS Library packages, dependencies, and libraries, including everything else you need to run the system.

Note

In our examples, we use the directory pyats, but you can give your directory a different name.

Create a new directory:
```
$ mkdir pyats
```
Go to the new directory:
```
$ cd pyats
```
Initialize a virtual environment in this directory:
```
$ python3 -m venv .
```
Result: This creates a project “folder” (space) within the current directory. The folder keeps all dependencies, features, and components together in one place.
Activate the virtual environment:
```
$ source bin/activate .
```

Result: The system displays the directory in parentheses before the command prompt:
(pyats)$
When you install the pyATS ecosystem within this virtual environment, the packages remain separate from those in other project spaces.
Hint

When you’re done with your pyATS session, you can close the terminal window or exit the environment:
$ deactivate

Pip Install

If you haven’t already done so, activate your virtual environment:
```
$ source bin/activate
```
Result: The system displays the directory in parentheses before the command prompt:
```
(pyats)$
```
Upgrade pip with the latest setup tool packages:
```
$ pip install --upgrade pip setuptools
```

Install pyATS and the pyATS Library, using the options described in the following table.

Installation options
Installation option	Command	Includes
Full	`$ pip install pyats[full]`	All pyATS and pyATS Library infrastructure pyATS Library network automation packages Optional extras (templates and the Robot Framework plug-in)
Standard	`$ pip install pyats[library]`	All pyATS and pyATS Library infrastructure pyATS Library network automation packages
Core pyATS	`$ pip install pyats`	pyATS bare-bone infrastructure
Robot Framework	`$ pip install pyats[robot]`	Optional Robot Framework package `pyats.robot` package (contains pyATS-specific keywords)
Template command	`$ pip install pyats[template]`	Enables use of the `template` command, which prompts you for input at runtime
Individual packages (for three-part patch versions)	`$ pip install <package_name>`	The specified package

Hint

Give the installer a few minutes to finish.

Result: You’re ready to start using pyATS and the pyATS Library!

Note

If you see warning messages, or the installation fails, first check your system requirements, especially your Linux and Python versions. If you need more help, contact us at
pyats-support-ext@cisco.com.

To test the installation, from the current (pyATS) directory, clone the Git examples repository:
```
git clone https://github.com/CiscoTestAutomation/examples
```

Run the following example:

pyats run job examples/basic/basic_example_job.py

Or, for DevNet community users who want to receive an email summary:
pyats run job examples/basic/basic_example_job.py --mailto <address>
Result: pyATS runs three sample test cases, displays a summary of the results, and emails you the summary.

Update Environment

On the last Tuesday of the month, the team releases a new version of pyATS. This topic describes how to get the latest changes.

To upgrade the pyATS and pyATS Library infrastructure, and any or all of the feature libraries and components, run the relevant upgrade command from your virtual environment.

Tip

You can find the latest information about releases on Twitter at #pyATS.

For information about all things pyATS, see our discussion on Webex Teams.

You can check and upgrade your pyATS installation straigth from the command line:

# to check your current pyats version
(pyats)$ pyats version check

# to check if any packages are out-dated
(pyats)$ pyats version check --outdated

# to update version
(pyats)$ pyats version update

Otherwise, you can also update the packages manually using Pip:

Pip upgrade options
Upgrade option	Command	Includes
Full	`$ pip install pyats[full] --upgrade`	All pyATS and pyATS Library infrastructure pyATS Library network automation packages Optional extras (templates and the Robot Framework plug-in)
Standard	`$ pip install pyats[library] --upgrade`	All pyATS and pyATS Library infrastructure pyATS Library network automation packages
Core pyATS	`$ pip install pyats --upgrade`	ATS infrastructure
Robot Framework	`$ pip install pyats[robot] --upgrade`	Optional Robot Framework package `pyats.robot` package (contains pyATS-specific keywords)
Template command	`$ pip install pyats[template] --upgrade`	Enables the use of the `template` command, which prompts you for input at runtime
Individual packages (for three-part patch versions)	`$ pip install <package_name> --upgrade`	The specified package

Result: The installer checks for and upgrades any dependencies, and gives you the latest version of the pyATS and pyATS Library core and library packages. To check the version:

(pyats) $ pyats version check

Result: The system displays a list of the packages and the installed versions.

Attention

The major and minor versions must all match. It’s okay if the patch version varies.

Using Docker

If you know how to use Docker, you can work with our pre-built docker image, which includes both pyATS and the pyATS Library. You can find the image and instructions at https://hub.docker.com/r/ciscotestautomation/pyats.

bash$ docker pull ciscotestautomation/pyats:latest

Examples Repository

We’ve provided some examples to help you start using the pyATS Library for some simple scenarios that demonstrate how the pyATS Library works.

Note

Make sure that you have pyATS and the pyATS Library fully installed.

To clone the Git repository from your virtual environment:

(|library|) $ git clone https://github.com/CiscoTestAutomation/examples

To download the Git repository from a browser:
- Go to https://github.com/CiscoTestAutomation/examples.
- Select Clone or download.
- Select Open in Desktop to download and use the GitHub Desktop app, or Download Zip to download and extract a zip file.

Result: You now have the example files stored in the examples directory.