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 | Node.js 20.x or higher |
| 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 |
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:
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:
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
Prebuilt binaries (recommended)
Run the ziskup installer:
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:
rustup toolchain list
The output should include an entry for zisk. Next, confirm that
the correct version of cargo-zisk was installed.
cargo-zisk --version
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.
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):
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:
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.
ziskup run removes the SNARK proving keyEach 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:
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:
# 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
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:
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:
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:
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:
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:
rustup toolchain list
The output should include an entry for zisk. Next, confirm that
the correct version of cargo-zisk was installed.
cargo-zisk --version
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
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:
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:
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:
. 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:
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:
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:
| Flag | Default | Effect |
|---|---|---|
--hash <HASH> | blake3 | Hash mode of the key: Poseidon1, Poseidon2 or blake3. |
--compressed-final <BOOL> | on | Build 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 poseidon | Proofs each recursive2 circuit aggregates. Must be 2 or 3. |
--setup-jobs <N> | 1 | Max concurrent AIRs during the non-recursive setup (env SETUP_JOBS). Size by available RAM. |
--recursive-jobs <N> | 1 | Max concurrent recursive1 pipelines (env RECURSIVE_JOBS). Size by available RAM. |
--recursive-n-bits <N> | per air | Pin every recursive air to 2^N rows (env RECURSIVE_N_BITS). Setup fails if an air needs more. |
--gen-exps | off | Generate 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> | auto | CUDA arch for --gen-exps: auto, major, "89,120" or sm_120. |
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:
cargo-zisk-dev check-setup
Add the --gpu flag if you built ZisK with GPU support:
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:
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/:
(cd .. && curl -fL -O https://storage.googleapis.com/zkevm/ptau/powersOfTau28_hez_final_24.ptau)
Then generate the SNARK proving key:
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:
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:
| Flag | Effect |
|---|---|
--provingkey | Installs the proving key and generates its constant trees. |
--verifykey | Installs 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. |
--nokey | Installs the binaries and toolchain only, without touching any proving or verify key. |
--blake3 | Installs the Blake3 key (the default). See Hash modes. |
--poseidon1 | Installs 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 / --cpu | Installs the GPU or CPU build (Linux only). Mutually exclusive. Without either, the GPU build is chosen when a compatible NVIDIA driver is found. |
-y, --yes | Non-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. |
--system | System-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. |
--force | With --system: re-install even if the bundle is already at the requested version. |
--with-snark | With --system only: also install the pilfflonk SNARK key of the same hash mode. Use ziskup setup_snark in user mode. |
--uninstall | Removes 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, --help | Prints 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
rustup uninstall zisk
rm -rf $HOME/.zisk
Remove the PATH entry added to ~/.bashrc manually.