Skip to main content

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:

ToolNotesInstall
RustStable toolchain. ZisK adds a second zisk toolchain for RISC-V cross-compilation.rustup.rs
GitRequired 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 setupNode.js 20.x or higher
Run proving on a GPUNVIDIA driver 525.60.13 or later
Use GPU acceleration through the zisk-sdk crateNVIDIA driver 525.60.13 or later and CUDA Toolkit 12.9 or later
Memory

Proving on the CPU has a large peak working set: about 43 GB for a STARK proof of the Quickstart example (more with --asm) and more than 60 GB for a CPU pilfflonk wrap. On Linux you need that much RAM or enough swap, otherwise the kernel OOM-kills the process. Building the proving key from source peaks at about 6.6 GB and produces a 17 GB key.

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, raise the memlock limit for login shells in /etc/security/limits.conf by adding the following lines:

* soft memlock unlimited
* hard memlock unlimited

Log out and back in for the change to take effect. If you run ZisK as a systemd service (for example a worker), the service limit comes from systemd instead: edit /etc/systemd/system.conf and add the following line, then reboot:

DefaultLimitMEMLOCK=infinity

Install ZisK​

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:

#OptionWhat it installsChoose if
1Install proving key (default)Full proving key with constant treesYou want to generate and verify proofs. Recommended for most users.
2Install proving key (no constant tree files)Proving key without pre-generated treesYou want to build the constant trees yourself to save upfront disk space.
3Install verify keyVerification key onlyYou only need to verify proofs, not generate them.
4NoneToolchain onlyYou 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)

The [device] field is [cpu] or [gpu] and names the build you installed. It is fixed when the binaries are built, not detected at run time. If you wanted the GPU build and it reports [cpu], re-run ziskup --gpu.

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.

Hash modes​

The proving key commits with one hash function, its hash mode. Since 1.4.0-alpha the default is Blake3. Pass --poseidon1 to install the Poseidon1 key instead (--blake3 selects the default explicitly):

bash
ziskup --poseidon1

Blake3 is 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 it buys extra margin if you would rather not depend on the security of an algebraic construction.

The hash mode is a property of the key, not of the binaries. Program setups, verification keys and proofs are per hash mode: a proof verifies only under the keys of the mode it was produced with, and the on-chain verifier contract must match it (zisk-contracts/blake3/ or zisk-contracts/poseidon1/). Re-running ziskup with the other flag replaces the installed key and clears the cache, so program setups are regenerated on the next run.

Install the SNARK proving key​

This step is kept separate because it is not required for most users. You only need the SNARK proving key if you intend to generate final SNARK proofs (--pilfflonk) for on-chain verification. It is also large, a 4.67 GB download that takes about 6.3 GB on disk once installed, so only install it if you actually need it:

bash
ziskup setup_snark

The final SNARK is pilfflonk, for both hash modes. setup_snark installs the pilfflonk key of the same hash mode as your proving key (zisk-provingkey-pilfflonk-<setup_version>.tar.gz for Blake3, zisk-provingkey-pilfflonk-<setup_version>-poseidon1.tar.gz for Poseidon1) into ~/.zisk/provingKeySnark. It takes no flags: the hash mode is read from the installed bundle, and a bundle that records none is treated as Poseidon1. See Choosing a proof format.

Every ziskup run removes the SNARK proving key

Each ziskup run reinstalls the toolchain, and the toolchain installer cleans ~/.zisk: it deletes every file there, including the .zisk-bundle state file, and every directory except bin/, toolchains/, provingKey/, verifyKey/, cache/ and zisk/. The SNARK proving key in ~/.zisk/provingKeySnark (about 6 GB) is lost, as are pil2-proofman/ and recurser/. With the bundle state gone, the hash mode can also be detected wrongly: ziskup setup_snark falls back to Poseidon1 when the bundle records none. Pass --blake3 or --poseidon1 explicitly on every ziskup run, then re-install the SNARK key with ziskup setup_snark and check the hash mode in the Installing SNARK proving key for ZisK version … (<mode>) line it prints.

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)

The [device] field is [cpu] or [gpu] and is fixed at build time. If you expected [gpu] but it reports [cpu], CUDA was not detected when you built. Install the CUDA Toolkit and rebuild.


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.

The steps below source a helper script, tools/test-env/setup_common.sh, and reuse the variables it exports ($INCLUDE_PATHS, $PROOFMAN_DIR and the circuit paths), so run all of them in the same bash session. The script needs ROOT_DIR set to the zisk/ folder. From that folder, run:

bash
export ROOT_DIR=$PWD

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
cargo run --release --bin jump-dest-bitmap-table-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 setup/starkstructs.blake3.json \
--hash blake3 \
--recursive

This generates the $HOME/.zisk/provingKey directory, where cargo-zisk looks for the key at proving time. For a Poseidon1 key, use --stark-structs setup/starkstructs.poseidon.json --hash Poseidon1 instead.

Other proofman-setup setup options:

FlagDefaultEffect
--hash <HASH>blake3Hash mode of the key: Poseidon1, Poseidon2 or blake3.
--compressed-final <BOOL>onBuild the vadcop_final_compressed stage. A key built without it can gain it later with setup-compressed-final.
--agg-arity <N>2 for blake3, 3 for poseidonProofs each recursive2 circuit aggregates. Must be 2 or 3.
--setup-jobs <N>1Max concurrent AIRs during the non-recursive setup (env SETUP_JOBS). Size by available RAM.
--recursive-jobs <N>1Max concurrent recursive1 pipelines (env RECURSIVE_JOBS). Size by available RAM.
--recursive-n-bits <N>per airPin every recursive air to 2^N rows (env RECURSIVE_N_BITS). Setup fails if an air needs more.
--gen-expsoffGenerate and compile the per-AIR CUDA kernels at the end of setup. No-op if nvcc is not found on PATH, under $CUDA_HOME/bin or under /usr/local/cuda/bin.
--exps-arch <SPEC>autoCUDA arch for --gen-exps: auto, major, "89,120" or sm_120.
note

Verification only trusts release keys by default. A key built from the unmodified release sources produces the same vadcop_final.verkey.json as the release key, so its proofs verify as is. If you changed the circuit or the setup options, pass your key's vadcop_final.verkey.json to cargo-zisk verify --leaf-setup-vk, and for a pilfflonk proof from your own SNARK key also its pilfflonk.vkey.json with --pilfflonk-vk. See Verify.

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 SNARK proving key that wraps the STARK proof into a compact pilfflonk 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
(cd .. && curl -fL -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.

--final-snark selects the protocol and defaults to pilfflonk, the only one a Blake3 key takes. plonk and fflonk need a Poseidon key (setup --hash Poseidon1 or Poseidon2). A PLONK key is an advanced option: no PLONK verifier contract ships with the release, and you must prove with --plonk and verify with --plonk-vk. Other options: --only-recursive-final (generate only the recursivef step), --extra-muls <N> (pilfflonk grouping) and --exps-arch <SPEC> (default major).


Updating​

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

bash
ziskup

Every run installs the binaries (and, in user mode, the toolchain), then the key you choose. Without a key flag, ziskup prompts for one, and for the CPU or GPU build when no compatible NVIDIA driver is detected. Pass flags to skip the prompts:

FlagEffect
--provingkeyInstalls the proving key and generates its constant trees.
--verifykeyInstalls the verify key only. Useful for verifier nodes that do not need to generate proofs. The key is extracted into ~/.zisk/provingKey, not ~/.zisk/verifyKey.
--nokeyInstalls the binaries and toolchain only, without touching any proving or verify key.
--blake3Installs the Blake3 key (the default). See Hash modes.
--poseidon1Installs the Poseidon1 key instead of the default Blake3 one.
-v, --version <X>Installs version <X> instead of the latest release. Pass it without the leading v (for example 1.4.0-alpha); ziskup adds it, and -v v1.4.0-alpha fails with gzip: stdin: not in gzip format.
--gpu / --cpuInstalls the GPU or CPU build (Linux only). Mutually exclusive. Without either, the GPU build is chosen when a compatible NVIDIA driver is found.
-y, --yesNon-interactive: accept the defaults (the proving key, and the CPU build if no compatible driver is found). Without it, ziskup reads its prompts from /dev/tty.
--arch <ARCH>Installs a specific architecture (amd64 or arm64).
--platform <PLATFORM>Installs a specific platform (linux or darwin).
--prefix <DIR>Installs to <DIR> instead of $HOME/.zisk.
--systemSystem-wide install for services (root required). Defaults --prefix to /opt/zisk and --owner to zisk:zisk (created if missing). Skips the toolchain and the PATH change.
--owner <U:G>chown the install tree to U:G after extraction.
--forceWith --system: re-install even if the bundle is already at the requested version.
--with-snarkWith --system only: also install the pilfflonk SNARK key of the same hash mode. Use ziskup setup_snark in user mode.
--uninstallRemoves the bundle. Only the subdirectories listed in the bundle manifest are deleted, which in user mode can be just toolchains/, leaving bin/, zisk/ and provingKey/ behind (see Uninstall). Combine with --system for the system bundle.
-h, --helpPrints the help.

Keys are named by setup version: the setup_version file shipped with the binaries, or the ZisK version when there is none. It can differ from the ZisK version.

A SNARK proving key installed with ziskup setup_snark does not survive a ziskup run; see Install the SNARK proving key.


Uninstall​

bash
rustup uninstall zisk
rm -rf $HOME/.zisk

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