PYNQ Command Line Interface

PYNQ provides a Command Line Interface (CLI) that is used to offer some basic functionalities directly within a shell.


The way it works is pretty simple: when you are in a shell session, you can type

pynq subcommand

to execute whatever the selected subcommand is designed to do.

By itself, the pynq root command is just a dispatcher: under the hood, when you type pynq subcommand it looks for an available executable named pynq-subcommand and runs it.

Therefore, to add new functionalities to the PYNQ CLI, it is sufficient to make a new executable available that follow this naming structure. For example, to manage instances of a device server, the pynq-server executable is created, and it will be called by typing pynq server in the command line.

Printing the Help Message

You can get the associated help message by typing

pynq --help

This will print the help message with the available options, as well a list of the available subcommands.

Printing the Version

To get the installed PYNQ version, you can type

pynq --version

This will also print out the hash of the commit ID from the PYNQ GitHub repository, that might be useful for diagnosing issues and bug reporting.

Available subcommands

Device Server Management

The pynq server command is used to manage instances of device servers. You can either start or stop the server by typing the intended command as follows

pynq server start

And you can also get a help message by typing

pynq server --help


As of now, we recommend not to use the pynq server subcommand on Zynq and Zynq Ultrascale+ devices, as the device server in these cases is already managed by a system service provided in the PYNQ SD card image.

Get the Available Notebooks

The pynq get-notebooks command is responsible for the delivery of notebooks.

pynq get-notebooks

This command will create a pynq-notebooks folder in your current working directory that will include notebooks and, possibly, associated overlays. The command will scan the environment for available notebooks coming from packages that have registered for discovery. You can read more about this mechanism in the Python Packaging section.

You may want to provide a specific path where to deliver the notebooks instead. You can achieve this by passing the --path option

pynq get-notebooks --path <your-path>

By default, typing get-notebooks without any option will deliver all the available notebooks and prompt the user for confirmation, listing what notebooks are detected and will be delivered. You can override this behavior by passing the special keyword all to the command. This will deliver all the notebooks directly, without asking for confirmation

pynq get-notebooks all

You can also choose to get only a number of selected notebooks by typing the name of the notebooks you want

pynq get-notebooks nb1 [nb2 ...]

You can get a list of the available notebooks by using the --list option

pynq get-notebooks --list

When running pynq get-notebooks overlays are potentially downloaded automatically from the network based on the target device. Therefore, there is the possibility that some overlays will not be available for your device, and you will have to synthesize the manually from source. In case the overlays associated with certain notebooks are not found for your device, these notebooks will not be delivered. If, however, you want to get the notebooks anyway, ignoring the automatic overlays lookup, you can pass the --ignore-overlays option.

pynq get-notebooks --ignore-overlays

Moreover, you can manually specify a target device by passing the --device option

pynq get-notebooks --device DEVICE

Or get a list of detected devices to choose from using the --interactive option instead.

pynq get-notebooks --interactive

The default behavior in case neither of these two options is passed, is to use the default device (i.e. pynq.Device.active_device) for overlays lookup.

After the command has finished, you can run the notebooks examples by typing:

cd pynq-notebooks
jupyter notebook

The get-notebooks command has a number of additional options that can be listed by printing the help message:

pynq examples --help

Please refer to the help message for more info about these options.