pip installation

This page describes how to install RADKit from its Python packages (a.k.a “wheels”). This installation method is for you if:

  • you plan to use RADKit as an SDK to develop automation;

  • you need to integrate RADKit with PyATS/Genie or another 3rd party library;

  • there is no RADKit installer available for your OS/architecture;

  • you need specific control over your Python packages/dependencies.

Danger

All RADKit releases available externally are cryptographically signed by Cisco. You should NEVER install a RADKit component whose code signature you have not been able to find and verify. See Code signing for more information.

Python environment

To install Python (see Supported Python versions), please refer to your operating system documentation. We strongly recommend setting up a virtual Python environment using a tool such as pyenv, venv or virtualenv.

Warning

Installation problems have been reported when adding the --user parameter to pip install and/or when a .local/ directory exists in the user’s home directory. In both cases, leaks have been observed between the global and virtual Python environments. As a consequence, we do not support installing RADKit with the --user parameter or if Python packages are present in the .local directory.

Installing from PyPI.org

Since version 1.8.5, RADKit is available on PyPI.org and can be installed using:

# To install RADKit Client only
python3 -m pip install cisco_radkit_client

# To install RADKit Service only
python3 -m pip install cisco_radkit_service

# To install BOTH
python3 -m pip install cisco_radkit_client cisco_radkit_service

There are only four official RADKit projects on PyPI.org:

All four projects have PyPI attestations set up with https://github.com/Cisco-RADKit-eng/publish as the only allowed source repository; you are however encouraged to pre-download the wheels and verify the code signatures (see Code signing) as an additional precaution before installing.

Installing from tarballs

An alternative way of getting the RADKit wheels is to visit the downloads area, get the RADKit wheels tarball for your system (see Supported OSes & architectures) and unpack it locally. Once the wheels are downloaded and unpacked, you are encouraged to verify the code signatures (see Code signing) before installing.

To install, open a Terminal or Command Prompt window, navigate to the directory where the wheels are located, and make sure that the correct virtual Python environment is activated. Finally, install RADKit by running pip from within that directory:

# To install RADKit Client only
python3 -m pip install -f . cisco_radkit_client

# To install RADKit Service only
python3 -m pip install -f . cisco_radkit_service

# To install BOTH
python3 -m pip install -f . cisco_radkit_client cisco_radkit_service

xcrun error on macOS

On macOS, if you encounter the error xcrun: error: invalid active developer path or something similar related to building some dependencies from source, you may need to install or reinstall Xcode (a macOS component) using the command: xcode-select --install (if the problem persists, try xcode-select --reset).

Starting RADKit

First activate the virtual environment where you ran the commands in the previous section. The different RADKit components can be started through the CLI from a shell:

  • radkit-client

  • radkit-control

  • radkit-interactive

  • radkit-medic-gui

  • radkit-network-console

  • radkit-service

  • radkit-service-gui

Warning

  • radkit-service-gui and radkit-medic-gui are currently not supported on Linux.

  • On macOS, the zsh shell keeps a cache of where executables are found in the PATH. In some situations where multiple instances of RADKit have been installed (especially when mixing installer-based and pip-based installations), it may be necessary to run the rehash command to find the most recent installation. In general, it is best to avoid mixing installation methods, to properly uninstall unused instances, and to keep a strict separation between concurrently installed RADKit instances by making proper use of virtual environments.

Upgrading RADKit

RADKit Client and Service have to be upgraded together if they are installed within the same Python environment.

This is due to a common dependency, cisco_radkit_common, that is used by both cisco_radkit_client and cisco_radkit_service. If e.g. only the Client package is updated, the Common package will be updated along with it and may become incompatible with the non-updated Service, causing run-time errors and/or other strange behavior. If you ever get into this situation, you will be warned by pip:

ERROR: pip's dependency resolver does not currently take into account all the packages that are installed. This behaviour is the source of the following dependency conflicts.
cisco-radkit-service 1.3.8 requires cisco-radkit-common==1.3.8, but you have cisco-radkit-common 1.4.0b14 which is incompatible.

Still, it is easy to miss this warning, especially because after displaying it, pip will still terminate successfully, so please pay close attention when upgrading.

Uninstalling RADKit

To uninstall RADKit, list all the installed RADKit packages using pip freeze and then run pip uninstall for all cisco_radkit_... packages.