PYNQ Edition! Building PYNQ Images

Following on in this MicroZed Chronicles series on the PYNQ framework, in this blog we are going to look at how we can create a PYNQ image…

Adam Taylor
4 years ago

Continuing this MicroZed Chronicles series on the PYNQ framework, in this blog we are going to look at how we can create a PYNQ image for our own board. Currently, there are official PYNQ images available for the following development boards:

  • Pynq Z1 — Zynq SoC 7020
  • Pynq Z2 — Zynq SoC 7020
  • ZCU104 — Zynq MPSoC XCZU7EV
  • ZCU111 — Zynq RFSoC XCZU28DR
  • Ultra96 — Zynq MPSoC ZU3EG

While these images cover a wide range of devices in the Zynq, Zynq MPSoC and Zynq RFSoC families of course there are times when we want to generate a PYNQ Image for a different board or even a custom board development.

Building an image is very straightforward and not as challenging as it may initially seem.

The first thing we need to do is clone the PYNQ repository from the Xilinx GitHub, using the command:

git clone

This will provide us all the necessary sources to rebuild existing images and create images our own boards.

The next step is to create a Linux build machine. When it comes to creating this build machine it is best to use either a virtual machine or an AWS instance. Using a new machine instance means that, if anything goes wrong during the configuration and build stages, you do not risk corrupting your main development system.

The requirements for this build machine are:

  • Ubuntu 16.04
  • 4 process cores
  • At least 8 GB of memory
  • At least 300 GB of hard disk space
  • Configure the machine for passwordless sudo operation

To help set up the VM, you can download Vagrant and Virtual Box — Vagrant helps us configure the virtual machine. If you look in the top level of the cloned git repository, you will see a vagrant file. Once Vagrant is installed, this file will help us configure the virtual machine.

If we do not have a pre-existing VM, we can create one using the command below, from a terminal program in the Pynq directory.

vagrant up

Using Vagrant to create the Pynq_VM.

This will create a new virtual machine called Pynq_VM, which you can see in under virtual box.

Once your virtual machine is started, the login and password are both Vagrant. On this virtual machine is up and running the final stage is to install the following tools:

  • Vivado 2018.3
  • SDK 2018.3
  • PetaLinux 2018.3

As I already have a Linux VM, I will be using that for the remainder of this blog.

We are then able to set up the system for building PYNQ, we do this by running the setup host script located under


The best way to create a PYNQ build is to start from an existing PetaLinux BS. If you are unfamiliar on how to do this, please see previous blogs in the MicroZed Chronicles (Petalinux for MiniZed, PetaLinux from scratch).

The first step in creating the new image is to make a new folder under the directory:


Under this directory you will see directories for each of the supported boards. Add a new folder with the name of your board.

For this example, I created an PYNQ image to run on the Cora board, hence the Cora directory.

Within this directory, we need to include a board specification file which defines the architecture, bitfile location, and PetaLinux BSP location. This file should be named .spec in this case it is named cora.spec.

ARCH_cora := arm

BSP_cora := cora_bsp.bsp

BITSTREAM_cora := base/base.bit

STAGE4_PACKAGES_cora:= ethernet

To ensure a timelier build time, before you start the VM to build the image ensure you have set the number of processors the VM can use appropriately for your machine. These are available under system settings of the pynq_vm.

We can then build the image using the command, from within the SDBuild directory.

Make BOARDS=cora

This may take a while to build; however, once the image is generated it will be available under the output directory, within the sdbuild directory.

We can then write this image to the SD card using an application like etcher, before we boot the Cora board.

With a generated SD card image, the first thing we want to see is the boot to ensure PYNQ is loaded correctly on the Cora board. To do this, I monitored the terminal window as the PYNQ image booted.

You can see a video of the PYNQ image booting below.

Once we are happy the image is booting correctly, I connected the Cora board to my network, and opened a browser on my PC navigating to Pynq:9090.

If we have built the image correctly, this will open a login page for the Jupyter notebooks. The password is xilinx.

From here, we can navigate around the Jupyter notebooks that are provided with the initial download and start working with them and creating our own notebooks.

Of course, to get the best from the PYNQ running on the Cora we need to be create overlays. We will look at how we do this as part of future PYNQ edition blogs.

You can find a more detailed step-by-sstep tutorial for building PYNQ for the Cora here.

See My FPGA / SoC Projects: Adam Taylor on

Get the Code: ATaylorCEngFIET (Adam Taylor)

Access the MicroZed Chronicles Archives with over 280 articles on the Zynq / Zynq MpSoC updated weekly at MicroZed Chronicles.

Adam Taylor
Adam Taylor is an expert in design and development of embedded systems and FPGA’s for several end applications (Space, Defense, Automotive)
Latest articles
Sponsored articles
Related articles
Latest articles
Read more
Related articles