Installation

In-browser playground

You can try Amaranth out without installing anything by visiting the Amaranth Playground. The playground webpage contains a fully 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 support WebAssembly, including Firefox, Chrome, and Edge.

System requirements

Amaranth HDL requires Python 3.8; it works on CPython 3.8 (or newer), and works faster on PyPy3.8 7.3.7 (or newer). Installation requires pip 23.0 (or newer).

For most workflows, Amaranth requires Yosys 0.40 (or newer). A compatible version of Yosys is distributed via PyPI 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 like GTKWave is invaluable for debugging. As an alternative to GTKWave, the Amaranth 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 via PyPI for most popular platforms by the YoWASP project.

Installing prerequisites

• Windows
• macOS
• Debian
• Arch Linux
• Other Linux

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.

Download GTKWave, either win32 or win64 binaries. GTKWave does not need to be installed; it can be unpacked to any convenient location and run from there.

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

> pip install --upgrade pip

Install Homebrew. Then, install Python and GTKWave by running:

$ brew install python gtkwave

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

$ pip install --upgrade pip

Install Python and GTKWave by running:

$ sudo apt-get install python3-pip gtkwave

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

$ sudo apt-get install yosys

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

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

$ pip3 install --user --upgrade pip

Install Python, pip, GTKWave and Yosys by running:

$ sudo pacman -S python python-pip gtkwave yosys

Install Python and GTKWave 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 of pip installed by running:

$ pip3 install --user --upgrade pip

Installing Amaranth

The latest release of Amaranth should work well for most applications. A development snapshot—any commit from the main 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
• macOS
• Linux
• Arch Linux

To install the latest release of Amaranth, run:

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

To install the latest release of Amaranth, run:

$ pip install --user --upgrade 'amaranth[builtin-yosys]'

If you did not install Yosys manually in the previous step, to install the latest release of Amaranth, run:

$ pip3 install --user --upgrade 'amaranth[builtin-yosys]'

If you did install Yosys manually in the previous step, run:

$ pip3 install --user --upgrade amaranth

To install the latest release of Amaranth, run:

$ sudo pacman -S python-amaranth

Development snapshot

• Windows
• macOS
• Linux

To install the latest development snapshot of Amaranth, run:

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

To install the latest development snapshot of Amaranth, run:

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

If you did not install Yosys manually in the previous step, to install the latest release of Amaranth, run:

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

If you did install Yosys manually in the previous step, run:

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

Editable development snapshot

• Windows
• macOS
• Linux

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 the amaranth 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 the pip install --editable .[builtin-yosys] command any time package dependencies may have been added or changed (notably after updating the snapshot with git). Otherwise, code using Amaranth may crash because of a dependency version mismatch.

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 --user --editable '.[builtin-yosys]'

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

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

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

If you did install Yosys manually in the previous step, omit [builtin-yosys] from the following commands.

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

$ git clone https://github.com/amaranth-lang/amaranth
$ cd amaranth
$ pip3 install --user --editable '.[builtin-yosys]'

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

$ cd amaranth
$ git pull --ff-only origin main
$ pip3 install --user --editable '.[builtin-yosys]'

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

Installing board definitions

Todo

Explain how to install https://github.com/amaranth-lang/amaranth-boards.