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).
Four 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. Included with the Xcode Command Line Tools. | brew install 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 |
A CPU STARK proof has a peak working set of about 43 GB, but on macOS it also completes on Macs with less RAM: macOS compresses memory and swaps, so proving is slower rather than failing.
zisk-sdk hostThe Xcode Command Line Tools are not enough to build ZisK from source or
to build any host program that depends on zisk-sdk. The proving library's
C++ build looks for the macOS SDK inside the full Xcode app
(/Applications/Xcode.app/.../MacOSX.sdk) and, without it, fails with:
fatal error: 'atomic' file not found
Either install the full Xcode app, or
point the build at the SDK of the Command Line Tools before running
cargo build:
export MAKEFLAGS="SDKPATH=$(xcrun --show-sdk-path)"
System dependencies
With the tools above in place, install the required system libraries:
brew tap riscv-software-src/riscv
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.
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. Re-running ziskup with the other
flag replaces the installed key and clears the cache, so program setups are
regenerated on the next run. See
Hash modes for more.
SNARK proving key (not supported on macOS)
The SNARK proving key, needed for final SNARK (pilfflonk) proofs for
on-chain verification, cannot be installed on macOS. ziskup setup_snark
exits with setup_snark is not supported on macOS, and --with-snark
with --system exits with --with-snark is not supported on macOS.
Generate SNARK proofs on a Linux machine; see
Install the SNARK 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:
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/zisk-transpiler-riscv \
target/release/zisk-coordinator \
target/release/zisk-worker \
target/release/libziskclib.a \
target/release/cargo-zisk-dev \
$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.
The steps below source a bash 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 default macOS shell, zsh, cannot
source it. Start that session from the zisk/ folder and set ROOT_DIR
to it:
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:
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.
The other proofman-setup setup options are listed in
Install on Linux.
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. 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
Generate the SNARK proving key
SNARK proofs are not supported on macOS (see SNARK proving key). To build a SNARK proving key, follow Generate the SNARK proving key on a Linux machine.
Updating
Re-run ziskup at any time to upgrade to the latest release:
ziskup
Every run installs the binaries and toolchain, then the key you choose.
Re-running ziskup replaces the installed bundle: installing a key deletes
the previous key and ~/.zisk/cache, and the toolchain installer removes every
other directory in ~/.zisk except bin/, toolchains/, provingKey/,
verifyKey/, cache/ and zisk/ (for example a provingKeySnark/ or
pil2-proofman/ left by an earlier install). Without a key
flag, ziskup prompts for one. Pass flags to skip the prompt:
| 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. |
-y, --yes | Non-interactive: accept the defaults (the proving key). 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 /Library/Application Support/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. |
--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. |
--gpu and --cpu apply to Linux only; macOS always gets the CPU build.
--with-snark and ziskup setup_snark are not supported on macOS. Keys are
named by setup version: the setup_version file shipped with the binaries,
or the ZisK version when there is none.
Uninstall
rustup uninstall zisk
rm -rf $HOME/.zisk
Remove the PATH entry added to ~/.zshenv manually.