Installation

Venus is distributed as a self-contained monorepo and is built from source via the top-level Makefile. This page walks through the prerequisites and the canonical install flow.

System Requirements

Venus currently supports Linux x86_64 and macOS platforms (see note below).

Note: On macOS, proof generation is not yet optimized, so some proofs may take longer to generate.

Required Tools

Ensure the following tools are installed:

Rust
Git
Node.js version 20.x or higher (used by the proving-key setup pipeline)

For GPU-accelerated proving, you also need:

An NVIDIA GPU with a driver matching the installed CUDA toolchain.
The CUDA Toolkit.

Installing System Dependencies

Ubuntu

Ubuntu 22.04 or higher is required.

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

Venus uses shared memory to exchange data between processes. The system must be configured to allow enough locked memory per process:

$ ulimit -l
unlimited

A way to achieve this is to edit /etc/systemd/system.conf and add the line DefaultLimitMEMLOCK=infinity. Reboot for changes to take effect.

macOS

macOS 14 or higher is required.

You must have Homebrew and Xcode installed.

brew reinstall jq curl libomp protobuf openssl nasm pkgconf open-mpi libffi nlohmann-json libsodium riscv-tools

Installing Venus

1. Clone the Repository

git clone https://github.com/cysic-labs/venus.git
cd venus

2. Run `make setup`

The top-level Makefile drives the entire install pipeline -- building the Venus tools, installing the Rust zkVM toolchain, generating the proving key, and preparing the bundled zec-reth guest:

make setup

This is equivalent to the following sub-targets, run in order:

Step	Target	What it does
1	`build`	Builds Venus with GPU support (`cargo build --release --features gpu -p cargo-zisk --bin cargo-zisk`).
2	`install-toolchain`	Installs the Rust zkVM toolchain (`cargo-zisk sdk install-toolchain`) if not already present.
3	`check-key` -> `generate-key`	Builds and generates the proving key under `./build/provingKey` (this step takes ~30-45 minutes).
4	`build-guest`	Compiles the bundled `zec-reth` guest ELF.
5	`rom-setup`	Generates ROM setup files for the guest.
6	`compile-key`	Validates the proving key against the ROM (`check-setup`).

The generate-key step runs the bundled PIL pipeline:

npm install inside pil2-compiler/ and pil2-proofman-js/.
Generates fixed data (arith_frops_fixed_gen, binary_basic_frops_fixed_gen, binary_extension_frops_fixed_gen).
Compiles pil/zisk.pil into pil/zisk.pilout.
Runs main_setup.js to produce build/provingKey.

Once make setup finishes, the Venus CLI binary lives at target/release/cargo-zisk and the proving key is at build/provingKey.

3. Verify the Installation

./target/release/cargo-zisk --version
rustup toolchain list   # should include `zisk`

Optional: Add Venus to your PATH

If you would like to use the CLI from outside the repository, install the binaries to ~/.zisk/bin and add it to your PATH:

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 $HOME/.zisk/bin

PROFILE=$([[ "$(uname)" == "Darwin" ]] && echo ".zshenv" || echo ".bashrc")
echo "export PATH=\"\$PATH:$HOME/.zisk/bin\"" >> $HOME/$PROFILE
source $HOME/$PROFILE

Note: On Linux x86_64 the assembly emulator also needs the following files copied to ~/.zisk/zisk/:
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
cp -r ./lib-c $HOME/.zisk/zisk

Common Build Issues

`stddef.h` not found on Ubuntu

If you encounter:

--- stderr
/usr/lib/x86_64-linux-gnu/openmpi/include/mpi.h:237:10: fatal error: 'stddef.h' file not found

resolve it as follows:

Locate stddef.h:
```
find /usr -name "stddef.h"
```

Set the include paths (example for GCC 13):

export C_INCLUDE_PATH=/usr/lib/gcc/x86_64-linux-gnu/13/include
export CPLUS_INCLUDE_PATH=$C_INCLUDE_PATH

Re-run make setup.

Building from Toolchain Source

cargo-zisk sdk install-toolchain installs the Rust zkVM toolchain from prebuilt binaries. If you prefer to build it from source, first ensure you have the Rust build dependencies, then run:

./target/release/cargo-zisk sdk build-toolchain

Cleaning Up

make clean   # remove ./target, ./tmp, and guest build artifacts
make purge   # also remove ./build/provingKey, ./pil/zisk.pilout, and node_modules

Uninstalling

rustup uninstall zisk            # remove the zkVM toolchain
rm -rf $HOME/.zisk               # remove copied binaries (if installed)