Install on Linux

This guide will show you how ZisK can be installed from prebuilt binaries or built from source. Prebuilt binaries are the fastest way to get started and cover most use cases.

Prerequisites

ZisK runs on Linux on x86_64 and requires Ubuntu 22.04 or later.

Two tools must be installed before you install ZisK:

Tool	Notes	Install
Rust	Stable toolchain. ZisK adds a second zisk toolchain for RISC-V cross-compilation.	rustup.rs
Git	Required to clone the ZisK repository when building from source.	sudo apt-get install -y git

Depending on what you plan to do, you may also need:

If you want to…	Additional requirement
Build the proving setup	Docker
Run proving on a GPU	NVIDIA driver 525.60.13 or later
Use GPU acceleration through the zisk-sdk crate	NVIDIA driver 525.60.13 or later and CUDA Toolkit 12.9 or later

System dependencies

With those requirements in place, install the required system libraries:

bash

sudo apt-get install -y \
  xz-utils jq curl build-essential qemu-system libomp-dev libgmp-dev \
  nlohmann-json3-dev protobuf-compiler uuid-dev libgrpc++-dev \
  libsecp256k1-dev libsodium-dev libpqxx-dev nasm libopenmpi-dev \
  openmpi-bin openmpi-common libclang-dev clang gcc-riscv64-unknown-elf

This installs the OpenMP runtime for multi-threaded proving, the Protocol Buffers compiler, cryptographic libraries, the NASM assembler, the OpenMPI runtime, and the RISC-V cross-compiler toolchain. All of them are linked at compile time when building ZisK or its host programs.

Shared memory configuration

ZisK uses shared memory to exchange data between processes. The system must allow enough locked memory per process. Verify the current limit:

bash

ulimit -l

The output should be unlimited. If it is not, edit /etc/systemd/system.conf and add the following line:

DefaultLimitMEMLOCK=infinity

Reboot for the change to take effect.

---

Install ZisK

Prebuilt binaries (recommended)

Run the ziskup installer:

bash

curl https://raw.githubusercontent.com/0xPolygonHermez/zisk/main/ziskup/install.sh | bash

During installation, ziskup detects whether CUDA is available on your machine. If it is, ZisK is installed with GPU support; otherwise you are prompted to choose between the CPU binaries (default) or the GPU binaries.

You are then prompted to select a setup option:

#	Option	What it installs	Choose if
1	Install proving key (default)	Full proving key with constant trees	You want to generate and verify proofs. Recommended for most users.
2	Install proving key (no constant tree files)	Proving key without pre-generated trees	You want to build the constant trees yourself to save upfront disk space.
3	Install verify key	Verification key only	You only need to verify proofs, not generate them.
4	None	Toolchain only	You only want to write and test guest code without proving.

After installation, open a new terminal (or source ~/.bashrc) and verify the toolchain and CLI:

bash

rustup toolchain list

The output should include an entry for zisk. Next, confirm that the correct version of cargo-zisk was installed.

bash

cargo-zisk --version

bash

cargo-zisk X.X.X [device] (commit DATETIME)

If you opted for the GPU installation but the [device] field reports CPU instead of GPU, the CUDA driver is missing. Install the NVCC compiler and then repeat the installation.

If everything is correct, you're all set! Head to the Quickstart to write and prove your first program.

info

If you selected option 3 or 4 and want to generate proofs locally, you will need to build your own proving key since you chose not to download one. See Building the proving key.

Blake3 proving key

By default the proving key commits with Poseidon1. Pass the --blake3 flag to install a proving key that uses Blake3 instead:

bash

ziskup --blake3

Blake3 is offered as the conservative choice. Recent research has widened the known attack surface of Poseidon-family hashes. Poseidon1 is not broken and remains safe to use, but Blake3 is a long-studied, non-algebraic hash, so switching to it buys extra margin if you would rather not depend on the security of an algebraic construction.

Install the PLONK proving key

This step is kept separate because it is not required for most users. You only need the PLONK proving key if you intend to generate PLONK proofs for on-chain verification. It is also large, adding around 50 GB of data to disk, so only install it if you actually need it:

bash

ziskup setup_snark

note

This step requires a Poseidon1 proving key. If you installed ZisK with --blake3, ziskup setup_snark exits with an error — there is no SNARK proving key for the Blake3 variant yet. Support is planned for the next release. See Blake3 proving key.

Building from source

Building from source gives you full control over the ZisK binaries and is the right choice if you want to modify the toolchain, track a specific commit, or cannot use the prebuilt installer for your environment.

Clone and build

Start by cloning the ZisK repository and compiling the release binaries. The build produces the CLI, the emulator, the RISC-V transpiler, and the coordinator and worker binaries used for distributed proving:

bash

git clone https://github.com/0xPolygonHermez/zisk.git
cd zisk
cargo build --release

This step can take several minutes on first run as Cargo downloads and compiles all dependencies.

The build process automatically detects whether CUDA is available on your machine. If so, it builds the GPU-enabled binaries; otherwise, it builds the CPU version. To force the CPU version, use the --features cpu-only flag. By default, the build also auto-detects the GPU architecture of the host machine. Use the CUDA_ARCHS environment variable to control which architectures are compiled:

bash

# Single architecture (faster build — e.g. Ada Lovelace sm_89 / RTX 4090)
CUDA_ARCHS="89" cargo build --release

# Multiple architectures (e.g. Ada + Hopper)
CUDA_ARCHS="89,90" cargo build --release

# All major architectures — portable binary for distribution
# (sm_80, sm_86, sm_89, sm_90, sm_100, sm_120 + PTX forward compatibility)
# Note: this takes significantly longer to compile
CUDA_ARCHS="major" cargo build --release

warning

If you encounter a compilation error on Ubuntu referencing a missing stddef.h:

fatal error: 'stddef.h' file not found

Locate stddef.h and set the include paths:

bash

find /usr -name "stddef.h"
export C_INCLUDE_PATH=/usr/lib/gcc/x86_64-linux-gnu/13/include
export CPLUS_INCLUDE_PATH=$C_INCLUDE_PATH

Then try building again.

Install the binaries

Once the build finishes, copy the produced binaries and the assembly ROM setup files required by the fast ASM execution backend:

bash

mkdir -p $HOME/.zisk/bin
cp target/release/cargo-zisk \
   target/release/ziskemu \
   target/release/zisk-transpiler-riscv \
   target/release/zisk-coordinator \
   target/release/zisk-worker \
   target/release/libziskclib.a \
   target/release/cargo-zisk-dev \
   $HOME/.zisk/bin

cp target/zisk-libs/libziskc.a $HOME/.zisk/bin

mkdir -p $HOME/.zisk/zisk/emulator-asm
cp -r ./emulator-asm/src $HOME/.zisk/zisk/emulator-asm
cp ./emulator-asm/Makefile $HOME/.zisk/zisk/emulator-asm

mkdir -p $HOME/.zisk/zisk/lib-c/c
cp -r ./lib-c/c/src $HOME/.zisk/zisk/lib-c/c

Add the binaries to your PATH

Add ~/.zisk/bin to your system PATH:

bash

PROFILE=$([[ "$(uname)" == "Darwin" ]] && echo ".zshenv" || echo ".bashrc")
echo >>$HOME/$PROFILE && echo "export PATH=\"\$PATH:$HOME/.zisk/bin\"" >> $HOME/$PROFILE
source $HOME/$PROFILE

Install the ZisK Rust toolchain

ZisK uses a custom Rust toolchain to cross-compile guest programs to the riscv64ima-zisk-zkvm-elf target. Install it with:

bash

cargo-zisk toolchain install

This downloads prebuilt toolchain binaries and registers them with rustup. If you prefer to build the toolchain from source instead, ensure the dependencies required to build the Rust toolchain are installed, then run cargo-zisk toolchain build. Note that this takes significantly longer.

Verify the installation

After installation, verify the toolchain:

bash

rustup toolchain list

The output should include an entry for zisk. Next, confirm that the correct version of cargo-zisk was installed.

bash

cargo-zisk --version

bash

cargo-zisk X.X.X [device] (commit DATETIME)

If you opted for the GPU installation but the [device] field reports CPU instead of GPU, the CUDA driver is missing. Install the CUDA driver and then repeat the installation.

---

Building the proving key

note

Most users do not need this section. If you installed ZisK via ziskup and selected option 1 or 2, you already have a prebuilt proving key and can skip this entirely. Only continue here if you built ZisK from source and need to generate the proving key yourself.

The proving key encodes the arithmetic constraints of the ZisK circuit and is required to generate proofs. Building it from scratch takes 45 to 60 minutes and requires Node.js 20.x or higher. You only need to do this once per ZisK version.

Generate fixed data

Fixed data contains precomputed arithmetic tables used by the ZisK state machines. These are constant across all executions and must be generated before the circuit can be compiled. Run from the zisk/ folder:

bash

cargo run --release --bin zisk-arith-frops-fixed-gen
cargo run --release --bin zisk-binary-basic-frops-fixed-gen
cargo run --release --bin zisk-binary-extension-frops-fixed-gen

Compile the ZisK PIL

PIL (Polynomial Identity Language) is the constraint language ZisK uses to describe its circuit. This step compiles pil/zisk.pil into a binary representation that the setup tool can process:

bash

. tools/test-env/setup_common.sh && cargo-zisk-dev proofman-setup compile-pil \
  --pil pil/zisk.pil \
  --include "$INCLUDE_PATHS" \
  --output pil/zisk.pilout \
  --fixed-dir tmp/fixed \
  --fixed-to-file \
  --no-proto-fixed-data

This produces pil/zisk.pilout, the compiled circuit description that the next steps read as input.

Generate the PIL helpers

Generate the Rust helper code derived from the compiled circuit:

bash

cargo run --release --manifest-path "$PROOFMAN_DIR/Cargo.toml" --bin proofman-cli -- \
  pil-helpers \
  --pilout pil/zisk.pilout \
  --path pil/src \
  -o

Generate the STARK proving key

This is the longest step, typically 30 to 45 minutes. It reads the compiled circuit and generates the cryptographic parameters the prover needs at runtime: commitment keys, evaluation domains, and precomputed polynomial evaluations:

bash

cargo-zisk-dev proofman-setup setup \
  --airout pil/zisk.pilout \
  --build-dir $HOME/.zisk \
  --fixed-dir tmp/fixed \
  --stark-structs state-machines/starkstructs.json \
  --recursive

This generates the $HOME/.zisk/provingKey directory, where cargo-zisk looks for the key at proving time.

Optionally, pre-generate the constant trees the proving key relies on. If they aren't found, the first cargo-zisk prove builds them automatically. This step is optional, but running it now moves that one-time cost out of your first proof:

bash

cargo-zisk-dev check-setup

Add the --gpu flag if you built ZisK with GPU support:

bash

cargo-zisk-dev check-setup --gpu

Generate the expression files

This step is a GPU-only optimization and applies only if you built ZisK with CUDA support. By default, the prover evaluates each AIR's quotient expression through a bytecode interpreter. This step compiles those expressions ahead of time into one native CUDA kernel per AIR, written as an .exps.so next to the AIR's .bin inside the proving key. The prover picks each kernel up by convention and falls back to the interpreter for any AIR that doesn't have one, so the step is safe to skip and safe to repeat.

Run it against the proving key you generated above:

bash

cargo run --release --bin cargo-zisk-dev -- proofman-setup gen-exps --proving-key "$HOME/.zisk/provingKey" --arch major

Generate the SNARK proving key

This step is only needed if you intend to submit proofs for on-chain verification. It generates a Plonk proving key that wraps the STARK proof into a compact SNARK, which is the format required by on-chain verifier contracts. If you are only generating and verifying proofs off-chain, skip this step.

First, download the powers-of-tau file into the parent folder of zisk/:

bash

curl -L -O https://storage.googleapis.com/zkevm/ptau/powersOfTau28_hez_final_24.ptau

Then generate the SNARK proving key:

bash

cargo-zisk-dev proofman-setup setup-snark \
  --build-dir $HOME/.zisk \
  --publics-info state-machines/publics.json \
  --powers-of-tau powersOfTau28_hez_final_24.ptau

The result is stored under the $HOME/.zisk/provingKeySnark directory.

---

Updating

Re-run ziskup at any time to upgrade to the latest release:

bash

ziskup

Pass flags to skip the interactive prompt:

Flag	Effect
(none)	Installs the toolchain, the proving key, and the verify key. Equivalent to selecting options 1 and 3 at the interactive prompt.
--provingkey	Installs or updates the proving key and constant trees only. Use this to refresh the key after a new release without reinstalling everything.
--verifykey	Installs or updates the verify key only. Useful for verifier nodes that do not need to generate proofs.
--nokey	Updates the toolchain and CLI binaries only, without touching any proving or verify key. Use this for toolchain-only upgrades.
--blake3	Installs the Blake3 proving key instead of the default Poseidon1 one, as a more conservative hash choice. SNARK wrapping is not available for this variant yet, so ziskup setup_snark cannot be used.

---

Uninstall

bash

rustup uninstall zisk
rm -rf $HOME/.zisk

Remove the PATH entry added to ~/.bashrc manually.