Install on macOS
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.
macOS works well for developing and testing with ZisK. You can write guest code, run it and generate proofs, all on your Mac. The main limitation is that the embedded ASM backend and GPU acceleration are Linux-only. On macOS, you'll always have to use the emulator backend for execution and proving.
Prerequisites
ZisK runs on macOS 14 Sonoma or later, on both Intel (x86_64) and Apple Silicon (arm64).
Three tools must be installed before you install ZisK:
| Tool | Notes | Install |
|---|---|---|
| Xcode Command Line Tools | Needed to compile C/C++ dependencies. Without it the build fails at linking. | developer.apple.com |
| Homebrew | Used to install system libraries not available on macOS by default. | brew.sh |
| 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 |
System dependencies
With the tools above in place, install the required system libraries:
brew reinstall \
jq curl libomp protobuf openssl nasm pkgconf open-mpi \
libffi nlohmann-json libsodium riscv-tools
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.
Install ZisK
Prebuilt binaries (recommended)
Run the ziskup installer:
curl https://raw.githubusercontent.com/0xPolygonHermez/zisk/main/ziskup/install.sh | bash
During installation you will be 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 ~/.zshenv) 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 [cpu] (commit DATETIME)
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.
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:
ziskup setup_snark
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.
Install the binaries
Once the build finishes, copy the produced binaries to ~/.zisk/bin,
which is the directory cargo-zisk expects to find them in:
mkdir -p $HOME/.zisk/bin
cp target/release/cargo-zisk \
target/release/ziskemu \
target/release/riscv2zisk \
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
Assembly ROM setup files are only required on Linux x86_64. Assembly execution is not supported on macOS, so this step can be skipped.
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 [cpu] (commit DATETIME)
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.
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 arith_frops_fixed_gen
cargo run --release --bin binary_basic_frops_fixed_gen
cargo run --release --bin 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:
cargo-zisk-dev proofman-setup compile-pil \
--pil pil/zisk.pil \
--include "pil,$(cargo metadata --format-version 1 2>/dev/null | jq -r '.packages[] | select(.name=="proofman") | .manifest_path' | sed 's|/proofman/Cargo.toml||')/pil2-components/lib/std/pil,state-machines,precompiles" \
--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 "$(cargo metadata --format-version 1 2>/dev/null | jq -r '.packages[] | select(.name=="proofman") | .manifest_path' | sed 's|/proofman/Cargo.toml||')/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 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:
cargo-zisk-dev check-setup
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/:
curl -L -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.
Updating
Re-run ziskup at any time to upgrade to the latest release:
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. |
Uninstall
rustup uninstall zisk
rm -rf $HOME/.zisk
Remove the PATH entry added to ~/.zshenv manually.