You're reading an old version of this documentation.
For the latest stable release version, please have a look at master.

Install and setup

Spinal is a Scala library so it requires setting up a Scala environment; there are many ways to do so. Also, it generates VHDL, Verilog or SystemVerilog, which can be used by many different tools. This section describes the supported way to install a SpinalHDL description to Simulation flow, but there can be many variations.

Mandatory requirements

Before you download the SpinalHDL tools, you need to install a Scala environment:

For instance, to install them on the Debian distribution:

sudo apt-get install openjdk-8-jdk
sudo apt-get install scala
echo "deb all main" | sudo tee /etc/apt/sources.list.d/sbt.list
echo "deb /" | sudo tee /etc/apt/sources.list.d/sbt_old.list
curl -sL "" | sudo apt-key add
sudo apt-get update
sudo apt-get install sbt

These tools enable to use Spinal; but without any other tools, it is limited to code generation.

Installing SBT in an internet-free environment


If you do not need this, you can skip to the next section: Recommended requirements.

Normally, SBT uses online repositories to download and cache your projects dependencies. This cache is located in several folders:

  • ~/.sbt

  • ~/.cache/JNA

  • ~/.cache/coursier

To set up an internet-free environment, you can:

  1. Set up an environment with internet

  2. Launch a Spinal command (see Using Spinal from CLI with SBT) to fetch dependencies (for instance using the getting started repository)

  3. Copy the caches to the internet-free environment.


You can get a portable SBT setup here:


You might be interested in SpinalNomad.

Create a SpinalHDL project

We have prepared a ready-to-go project for you the: getting started repository.

You can download it, or clone it.

The following commands clone the project into a new directory named MySpinalProject and initialize a fresh git history:

git clone --depth 1 MySpinalProject
cd MySpinalProject
rm -rf .git
git init
git add .
git commit -m "Initial commit from template"

The directory structure of a project


The structure described here is the default structure, but it can be easily modified.

In the root of the project are the following files:




Scala configuration for sbt

Scala configuration for mill, an alternative to sbt


The folder containing hardware descriptions


More Scala configuration

A text/markdown file describing your project


List of files to ignore in versioning


More configuration for mill


Configuration of rules to auto-format the code

As you probably guessed it, the interesting thing here is hw/. It contains four folders: spinal/, verilog/ and vhdl/ for your IPs and gen/ for IPs generated with Spinal.

hw/spinal/ contains a folder named after your project name. This name must be set in build.sbt (along with the company name) and in; and it must be the one in package yourprojectname at the beginning of .scala files.

In hw/spinal/yourprojectname/, are the descriptions of your IPs, simulation tests, formal tests; and there is Config.scala, which contains the configuration of Spinal.


sbt must be used only at the root of the project, in the folder containing build.sbt.

Using Spinal on SpinalHDL code

Now the tutorial shows how to use Spinal on SpinalHDL code depending on your development environment: