---
description: >-
  Validium Network has integrated zkSync Foundry as its development framework.
  Discover the steps to install and configure Foundry for zkSync effectively.
---

# Installation

***

This guide will walk you through installing Foundry ZKsync, a specialized toolchain for developing, testing, and deploying smart contracts on ZKsync. You can install Foundry ZKsync by using the `foundryup-zksync` installer, downloading precompiled binaries, or by building it from source.

### Installing with `foundryup-zksync` <a href="#installing-with-foundryup-zksync" id="installing-with-foundryup-zksync"></a>

`foundryup-zksync` is the official installer for the Foundry ZKsync toolchain. It allows you to easily install and manage the latest versions of `forge` and `cast`.

{% hint style="info" %}
Please note that this installation overrides any existing forge and cast binaries in `~/.foundry`. You can use forge without the `--zksync` flag for standard EVM chains. To revert to a previous installation, follow the instructions on [Using foundryup on the official Foundry website](https://book.getfoundry.sh/getting-started/installation#using-foundryup).
{% endhint %}

To install `foundryup-zksync`, follow these steps:

#### 1. Install via the provided script <a href="#id-1-install-via-the-provided-script" id="id-1-install-via-the-provided-script"></a>

{% code overflow="wrap" %}
```bash
curl -L https://raw.githubusercontent.com/matter-labs/foundry-zksync/main/install-foundry-zksync | bash
```
{% endcode %}

By default, this will install the latest (nightly) precompiled versions of `forge` and `cast`. To see more installation options, such as installing a specific version, run:

```bash
foundryup-zksync --help
```

#### Important Notes <a href="#important-notes" id="important-notes"></a>

* Currently, only `forge` and `cast` are supported for ZKsync. Other commands retain their original behavior but may not work as intended.
* **Windows Users**: You need to use Git BASH or WSL, as `foundryup-zksync` does not support PowerShell or Cmd, and we do not provide Windows executable binaries. Windows support is currently provided on a best-effort basis.

### Precompiled Binaries <a href="#precompiled-binaries" id="precompiled-binaries"></a>

Precompiled binaries are available for download from the [`foundry-zksync` GitHub releases page](https://github.com/matter-labs/foundry-zksync/releases). We recommend using the latest nightly build to stay up-to-date with the latest features and fixes.

#### Available Binaries <a href="#available-binaries" id="available-binaries"></a>

* **macOS (Intel)**: [foundry\_nightly\_darwin\_amd64.tar.gz](https://github.com/matter-labs/foundry-zksync/releases/download/nightly/foundry_nightly_darwin_amd64.tar.gz)
* **macOS (Apple)**: [foundry\_nightly\_darwin\_arm64.tar.gz](https://github.com/matter-labs/foundry-zksync/releases/download/nightly/foundry_nightly_darwin_arm64.tar.gz)
* **Linux (Intel)**: [foundry\_nightly\_linux\_amd64.tar.gz](https://github.com/matter-labs/foundry-zksync/releases/download/nightly/foundry_nightly_linux_amd64.tar.gz)
* **Linux (ARM)**: [foundry\_nightly\_linux\_arm64.tar.gz](https://github.com/matter-labs/foundry-zksync/releases/download/nightly/foundry_nightly_linux_arm64.tar.gz)

To download and install one of these binaries, follow these steps:

```bash
# Example for macOS Intel (amd64)
wget -qc https://github.com/matter-labs/foundry-zksync/releases/download/nightly/foundry_nightly_darwin_amd64.tar.gz -O - | tar -xz
# Move to a location in your PATH, for example:
sudo mv ./forge /usr/local/bin/
sudo mv ./cast /usr/local/bin/
```

Repeat for your platform, replacing the URL with the appropriate binary.

### Building from Source <a href="#building-from-source" id="building-from-source"></a>

If you prefer to build Foundry ZKsync from source, follow these steps:

#### Prerequisites <a href="#prerequisites" id="prerequisites"></a>

* **Rust Compiler and Cargo**: The easiest way to install them is via [rustup.rs](https://rustup.rs/).
* **Nightly Rust**: Foundry ZKsync generally supports only a specific nightly version of Rust, which is automatically set by the presence of a `rust-toolchain` file in the project.

#### Build Instructions <a href="#build-instructions" id="build-instructions"></a>

There are multiple ways to build from source:

**Option 1: Using `foundryup-zksync` flags**

To build from a specific branch or path:

```bash
# Build from the main branch
foundryup-zksync --branch main

# Build from a local path
foundryup-zksync --path path/to/foundry-zksync
```

**Option 2: Using Cargo**

You can install the toolchain directly using Cargo:

{% code overflow="wrap" %}
```bash
cargo install --git https://github.com/matter-labs/foundry-zksync --profile release --locked forge cast
```
{% endcode %}

**Option 3: Manually building from a local clone**

```bash
# Clone the repository
git clone https://github.com/matter-labs/foundry-zksync.git
cd foundry-zksync

# Install Forge
cargo install --path ./crates/forge --profile release --force --locked

# Install Cast
cargo install --path ./crates/cast --profile release --force --locked
```

### Installing for CI in GitHub Actions <a href="#installing-for-ci-in-github-actions" id="installing-for-ci-in-github-actions"></a>

To install Foundry ZKsync for CI pipelines, the latest precompiled binaries for your architecture can be downloaded directly from the release page. Below is an example for a GitHub Actions workflow:

```bash
steps:
  - name: Download binaries
    run: |
      wget -qc https://github.com/matter-labs/foundry-zksync/releases/download/nightly/foundry_nightly_linux_amd64.tar.gz -O - | tar -xz
      ./forge -V && ./cast -V
```

### Configuration <a href="#configuration" id="configuration"></a>

#### Using `foundry.toml` <a href="#using-foundrytoml" id="using-foundrytoml"></a>

Foundry is highly configurable through a `foundry.toml` file, located in the root of your project or any parent directory. For a full list of configuration options, see the [config package documentation](https://github.com/matter-labs/foundry-zksync/blob/main/crates/config/README.md#all-options).

**Profiles**

You can organize configuration options using profiles. The default profile is named `default`. See more about the [Default profile on `foundry-zksync` README](https://github.com/matter-labs/foundry-zksync/blob/main/crates/config/README.md#default-profile).

To switch profiles, use the `FOUNDRY_PROFILE` environment variable. You can also override specific settings using environment variables prefixed with `FOUNDRY_` or `DAPP_`, such as `FOUNDRY_SRC`.

**Initialization**

The `forge init` command generates a basic `foundry.toml` file, which you can extend as needed.

**Viewing Configuration**

To view your current configuration:

* Run `forge config` to see all options.
* Run `forge config --basic` for a simplified view (as initialized with `forge init`).
* You can generate a new `foundry.toml` file with `forge config --basic > foundry.toml`.

By default, `forge config` displays the active profile and its values. It also accepts the same arguments as `forge build`.

**Example `foundry.toml` for ZKsync**

Here's an example configuration for ZKsync with `zksolc` settings:

```bash
[profile.default]
src = 'src'
out = 'out'
libs = ['lib']

[profile.default.zksync]
compile = true
fallback_oz = true
mode = '3'
```

#### Additional Configuration <a href="#additional-configuration" id="additional-configuration"></a>

You can find additional setup and configurations guides in the [official Foundry Book](https://book.getfoundry.sh/):

* [Setting up VSCode](https://book.getfoundry.sh/config/vscode)
* [Shell autocompletions](https://book.getfoundry.sh/config/shell-autocompletion)

#### Private key setup with Foundry keystore <a href="#private-key-setup-with-foundry-keystore" id="private-key-setup-with-foundry-keystore"></a>

Follow these steps to securely store your wallet's private key to use it in Foundry projects:

1. **Extract Your Private Key:** If you are using the local era node, use a private key from the available rich accounts. Otherwise, find your personal wallet's private key. For MetaMask users, here's how to [export your wallet's private key](https://support.metamask.io/hc/en-us/articles/360015289632-How-to-export-an-account-s-private-key).
2. **Create a Foundry keystore:** Create a keystore and import your private key by running

```bash
cast wallet import myKeystore --interactive
# enter your PK when prompted, provide a password, and copy the returned address
```

It'll return an address (keystore address).

{% hint style="info" %}
Note that the name `myKeystore` is arbitrary and can be updated. For our docs, we've chosen this name for consistency. If you decide to use another name, be sure to reference it when using `cast`.
{% endhint %}

**Using the keystore**

When running commands that require a private key, like `forge create` or `cast send`, use `--account myKeystore --sender <KEYSTORE_ADDRESS>`. This will require you to enter the keystore password you provided before.
