Skip to main content

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.

info

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:

ToolNotesInstall
Xcode Command Line ToolsNeeded to compile C/C++ dependencies. Without it the build fails at linking.developer.apple.com
HomebrewUsed to install system libraries not available on macOS by default.brew.sh
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. 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 setupNode.js 20.x or higher
Memory

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.

Build from source or a zisk-sdk host

The 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:

bash
export MAKEFLAGS="SDKPATH=$(xcrun --show-sdk-path)"

System dependencies​

With the tools above in place, install the required system libraries:

bash
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​

Run the ziskup installer:

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

During installation you will be 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 ~/.zshenv) 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 [cpu] (commit DATETIME)

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. 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:

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.

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:

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
note

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:

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 [cpu] (commit DATETIME)

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 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
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. The other proofman-setup setup options are listed in Install on Linux.

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. 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

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:

bash
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:

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.
-y, --yesNon-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.
--systemSystem-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.
--forceWith --system: re-install even if the bundle is already at the requested version.
--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.

--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​

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

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