Skip to content

Instantly share code, notes, and snippets.

What would you like to do?
Guide for installing Chisel HDL native or using Jupiter Notebook

Chisel Bootcamp Usage and Installation Guide

The following document is intended to provide the steps in order to install and use Chisel in the Jupyter environment. Moreover you can find the installation steps of Chisel on your local machine.

Chisel Installation

This will walk you through installing Chisel and its dependencies:

  • sbt, which is the preferred Scala build system and what Chisel uses.
  • Firrtl, which compiles Chisel's IR down to Verilog. If you're building from a release branch of chisel3, separate installation of Firrtl is no longer required: the required jar will be automatically downloaded by sbt. If you're building chisel3 from the master branch, you'll need to follow the directions on the firrtl project to publish a local copy of the required jar.
  • Verilator, which compiles Verilog down to C++ for simulation. The included unit testing infrastructure uses this.

(Ubuntu-like) Linux

  1. Install Java

    sudo apt-get install default-jdk
  2. Install sbt, which isn't available by default in the system package manager:

    echo "deb /" | sudo tee -a /etc/apt/sources.list.d/sbt.list
    sudo apt-key adv --keyserver hkp:// --recv 642AC823
    sudo apt-get update
    sudo apt-get install sbt
  3. Install Verilator. We currently recommend Verilator version 3.904. Follow these instructions to compile it from source.

    1. Install prerequisites (if not installed already):

      sudo apt-get install git make autoconf g++ flex bison
    2. Clone the Verilator repository:

      git clone
    3. In the Verilator repository directory, check out a known good version:

      git pull
      git checkout verilator_3_904
    4. In the Verilator repository directory, build and install:

      unset VERILATOR_ROOT # For bash, unsetenv for csh
      autoconf # Create ./configure script
      sudo make install


Make sure you have Java 8 installed on your machine

And then brew install sbt verilator

In case you do not have the correct version of Verilator (3.902):

brew --repository (to understand where bre is installed, let's assume /usr/local/Homebrew)
cd /usr/local/Homebrew/Library/Taps/homebrew/homebrew-core/
git checkout 16ebe5f1843e6cb54856311ff0f676be53007329 -- Formula/verilator.rb
brew uninstall verilator (uninstall older verilator version)
brew unlink verilator (remove all links to previous version)
HOMEBREW_NO_AUTO_UPDATE=1 brew install verilator

Create new project

To create a new project starting from a pre-existing template clone the Chisel git repo:

git clone MyChiselProject
cd MyChiselProject

Test the example GCD project:

sbt 'testOnly gcd.GCDTester'
sbt 'test:runMain gcd.GCDMain --backend-name verilator'

Jupyter Chisel Installation

The following instructions necessary for the purpose of this full-day bootcamp if you want to run the tools on your local machine.

Setup Instructions

Run the instructions below for your particular situation. Note that we include a custom javascript file for Jupyter, so if you already have Jupyter installed, you still need to install the custom.js file.

Note: Make sure you are using Java 8 (NOT Java 9) and have the JDK8 installed. Coursier/jupyter-scala does not appear to be compatible with Java 9 yet as of January 2018.

If you do have multiple version of Java, make sure to select Java 8 (1.8) before running jupyter notebook:

  • On Linux:
sudo update-alternatives --config java

Type the number related to Java 8 and press Enter. Then check which is the current Java version

java -version
  • On Windows:
  1. In the Java Control Panel, click on the Java tab.
  2. Click View to display the Java Runtime Environment Settings
  3. Verify that the wanted Java Runtime version is enabled by checking the Enabled box.
  4. Click OK to save settings
  5. Click OK in Java Control Panel window to confirm changes and close the window.
  6. Try to run same applet and verify it is now running using wanted version of Java installed in your system.
  • On MacOS:
export JAVA_HOME=`/usr/libexec/java_home -v 1.8`; java -version

Miniconda Installation

Linux/MacOS Installation

  1. Download the installer: Miniconda installer for Linux Miniconda installer for MacOS

  2. In your Terminal window, run: Miniconda:

  3. Follow the prompts on the installer screens. If you are unsure about any setting, accept the defaults. You can change them later.

  4. To make the changes take effect, close and then re-open your Terminal window.

Windows Installation

  1. Download the installer: Miniconda installer for Windows

  2. Double click the '.exe' file

  3. Follow the instructions on the screens. If you are unsure about any setting, accept the defaults. You can change them later.

Local Installation of the Jupyter environment - Mac/Linux

Make sure you have python3.6 installed in your environment as well as pip3

Before going on with the local installation of Jupyter for Chisel create and run the Conda environment:

conda create -n chisel_bootcamp pip python=3.6
source activate chisel_bootcamp

First install Jupyter Scala.

Dependencies: openssh-client, openjdk-8-jre, openjdk-8-jdk (-headless OK for both), ca-certificates-java

First, use pip3 to install jupyter (or pip for python 2):

pip3 install jupyter

Then, clone this repo and run the installation script:

git clone
cd jupyter-scala && ./jupyter-scala

Now clone this repo and install the customization script. If you already have one, append this script to it.

git clone
cd generator-bootcamp
mkdir -p ~/.jupyter/custom
cp source/custom.js ~/.jupyter/custom/custom.js

And to start the bootcamp on your local machine:

jupyter notebook

Jupyter Usage

All the participants have access to a server with the tools needed for this full-day bootcamp. In order to access to the server visit

Insert "username" and "password" provided by the administrators and log in. You will be redirected to a ready-to-use Jupyter notebook

Local Jupyter Usage

If you do not have access to the server you can run the Jupyter Chisel bootcamp notebook on your local machine prior installation (see previous step)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment