Installation

In-browser playground

You can try Amaranth out without installing anything by visiting theAmaranth Playground. The playground webpage contains afully functional Python interpreter and an Amaranth toolchain that can simulate a design, display waveforms, and generate Verilog code. It works on all modern browsers that supportWebAssembly, including Firefox, Chrome, and Edge.

System requirements

Amaranth HDL requires Python 3.9; it works onCPython 3.9 (or newer), and works faster onPyPy3.9 7.3.7 (or newer). Installation requirespip 23.0 (or newer).

For most workflows, Amaranth requiresYosys 0.40 (or newer). Acompatible version of Yosys is distributed viaPyPI for most popular platforms, so it is usually not necessary to install Yosys separately.

Simulating Amaranth code requires no additional software. However, a waveform viewer likeSurfer orGTKWave is invaluable for debugging. As an alternative, theAmaranth Playground can be used to display waveforms for simple designs.

Synthesizing, placing and routing an Amaranth design for an FPGA requires the FPGA family specific toolchain. The open source iCE40, ECP5, MachXO2/3, Nexus, and Gowin toolchains are distributed viaPyPI for most popular platforms by theYoWASP project.

Installing prerequisites

Windows

Install Python, either from Windows Store or using the full installer. If using the full installer, make sure to install a 64-bit version of Python.

Before continuing, make sure you have the latest version ofpip installed by running:

> pip install --upgrade pip

macOS

InstallHomebrew. Then, install Python by running:

$brewinstallpython

Before continuing, make sure you have the latest version ofpip installed by running:

$pipinstall--upgradepip

Debian

Install Python by running:

$sudoapt-getinstallpython3-pip

On architectures other than x86_64 and AArch64, install Yosys by running:

$sudoapt-getinstallyosys

If Yosys 0.40 (or newer) is not available,build Yosys from source.

Before continuing, make sure you have the latest version ofpip installed by running:

$pip3install--user--upgradepip

Other Linux

Install Python from the package repository of your distribution.

On architectures other than x86_64 and AArch64, install Yosys from the package repository of your distribution.

If Yosys 0.40 (or newer) is not available,build Yosys from source.

Before continuing, make sure you have the latest version ofpip installed by running:

$pip3install--user--upgradepip

Installing Amaranth

The latest release of Amaranth should work well for most applications. A development snapshot—any commit from themain branch of Amaranth—should be similarly reliable, but is likely to include experimental API changes that will be in flux until the next release. With that in mind, development snapshots can be used to try out new functionality or to avoid bugs fixed since the last release.

Latest release

Windows

To install the latest release of Amaranth, run:

> pip install --upgrade amaranth[builtin-yosys]

macOS

To install the latest release of Amaranth, run:

$pipinstall--user--upgrade'amaranth[builtin-yosys]'

Linux

If youdid not install Yosys manually in theprevious step, to install the latest release of Amaranth, run:

$pip3install--user--upgrade'amaranth[builtin-yosys]'

If youdid install Yosys manually in the previous step, run:

$pip3install--user--upgradeamaranth

Development snapshot

Windows

To install the latest development snapshot of Amaranth, run:

> pip install"amaranth[builtin-yosys] @ git+https://github.com/amaranth-lang/amaranth.git"

macOS

To install the latest development snapshot of Amaranth, run:

$pipinstall--user'amaranth[builtin-yosys] @ git+https://github.com/amaranth-lang/amaranth.git'

Linux

If youdid not install Yosys manually in theprevious step, to install the latest release of Amaranth, run:

$pip3install--user'amaranth[builtin-yosys] @ git+https://github.com/amaranth-lang/amaranth.git'

If youdid install Yosys manually in the previous step, run:

$pip3install--user'amaranth @ git+https://github.com/amaranth-lang/amaranth.git'

Editable development snapshot

Windows

To install an editable development snapshot of Amaranth for the first time, run:

> git clone https://github.com/amaranth-lang/amaranth>cd amaranth> pip install --editable .[builtin-yosys]

Any changes made to theamaranth directory will immediately affect any code that uses Amaranth. To update the snapshot, run:

>cd amaranth> git pull --ff-only origin main> pip install --editable .[builtin-yosys]

Run thepipinstall--editable.[builtin-yosys] command any time package dependencies may have been added or changed (notably after updating the snapshot withgit). Otherwise, code using Amaranth may crash because of a dependency version mismatch.

macOS

To install an editable development snapshot of Amaranth for the first time, run:

$gitclonehttps://github.com/amaranth-lang/amaranth$cdamaranth$pipinstall--user--editable'.[builtin-yosys]'

Any changes made to theamaranth directory will immediately affect any code that uses Amaranth. To update the snapshot, run:

$cdamaranth$gitpull--ff-onlyoriginmain$pipinstall--user--editable'.[builtin-yosys]'

Run thepipinstall--editable.[builtin-yosys] command any time package dependencies may have been added or changed (notably after updating the snapshot withgit). Otherwise, code using Amaranth may crash because of a dependency version mismatch.

Linux

If youdid install Yosys manually in theprevious step, omit[builtin-yosys] from the following commands.

To install an editable development snapshot of Amaranth for the first time, run:

$gitclonehttps://github.com/amaranth-lang/amaranth$cdamaranth$pip3install--user--editable'.[builtin-yosys]'

Any changes made to theamaranth directory will immediately affect any code that uses Amaranth. To update the snapshot, run:

$cdamaranth$gitpull--ff-onlyoriginmain$pip3install--user--editable'.[builtin-yosys]'

Run thepip3install--editable.[builtin-yosys] command any time package dependencies may have been added or changed (notably after updating the snapshot withgit). Otherwise, code using Amaranth may crash because of a dependency version mismatch.

Installing board definitions