How to Set Up a Local Sui Devnet with Sui CLI

07 October 2026

Setting up a local Sui devnet using the Sui CLI lets you test Move modules and transactions without touching a public network or needing internet access. This guide walks you through the installation, configuration, and basic usage of a local Sui development environment.

Prerequisites

Before starting, ensure your system meets these requirements:

• A 64-bit operating system (Linux, macOS, or Windows with WSL2)
• Git installed and available in your PATH
• At least 4 GB of free disk space for the full Sui build
• Rust and Cargo installed (the Sui CLI compiles from source on first install)

You do not need a Sui wallet or any test tokens for a local devnet. The devnet creates its own genesis state with pre-funded accounts.

Installing the sui CLI

The recommended way to install the Sui CLI is via cargo, Rust's package manager. Run these commands in your terminal:

# Install Rust if you haven't already
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Add Rust to your PATH
source "$HOME/.cargo/env"

# Install the Sui CLI binaries
cargo install --git https://github.com/MystenLabs/sui.git --branch main sui

The --branch main flag installs the latest stable release. If you need a specific version, replace main with a release tag like testnet-v1.22.0. The first install compiles the entire Sui repository, which can take 15 - 30 minutes depending on your internet speed and CPU.

To verify the installation succeeded, run:

sui --version

You should see output similar to sui 1.22.0-....

Starting a local devnet

A local Sui devnet runs a single validator node on your machine. It creates a private network with its own genesis configuration. Use the sui start command:

sui start

The first time you run this, Sui generates a ~/.sui/sui_config directory containing:

• genesis.blob - the initial state of the network
• client.yaml - your CLI client configuration
• A set of key files for pre-funded accounts

The devnet listens on http://127.0.0.1:9000 by default. You should see log output indicating the validator is running and accepting connections.

Stopping the Devnet

Press Ctrl+C in the terminal where the devnet is running. This shuts down the validator cleanly. All data persists in the ~/.sui/sui_config directory unless you delete it.

Configuring the CLI to Use the Local Devnet

By default, the Sui CLI connects to the public testnet. To point it at your local devnet, set the environment variable:

export SUI_NETWORK=http://127.0.0.1:9000

To make this permanent, add the line to your shell profile (~/.bashrc, ~/.zshrc, etc.).

Alternatively, you can pass the --network flag with every sui client command, but the environment variable is more convenient.

Creating and Funding a Test Account

The local devnet comes with pre-configured accounts. To see them:

sui client addresses

You should see one or more addresses with balances in the local token. If you need a new account:

sui client new-address ed25519

This generates a new key pair and prints the address. The local devnet does not automatically fund new accounts - you must transfer tokens from an existing pre-funded address.

To check a balance:

sui client gas --address <YOUR_ADDRESS>

Publishing a move module

With the devnet running and your CLI configured, you can publish a Move package. Assuming you have a Move project in a directory called my_move_project:

sui client publish --gas-budget 10000000 ./my_move_project

The --gas-budget flag sets the maximum gas you're willing to spend. Local devnet gas is free, but the budget is still required. The command returns a transaction digest and the published package ID.

If you receive an execution error, check the "Move Abort Codes Explained for Sui and Aptos" page on this site for common causes.

Running Transactions

To call functions on a published module, use:

sui client call --package <PACKAGE_ID> --module <MODULE_NAME> --function <FUNCTION_NAME> --args <ARGUMENTS> --gas-budget 10000000

For example, if your module has a create function that takes an integer:

sui client call --package 0x1234... --module my_module --function create --args 42 --gas-budget 10000000

You can query the objects owned by an address with:

sui client objects --address <ADDRESS>

Resetting the Devnet

To start fresh with a clean genesis state, delete the config directory:

rm -rf ~/.sui/sui_config

Then run sui start again. This regenerates everything, including new pre-funded accounts.

Limitations of a Local Devnet

A local devnet is a single validator with no consensus. This means:

• Transactions finalize instantly (no block confirmations)
• No epoch changes or validator rotation
• Gas costs are not realistic (local gas is effectively zero)
• Some Sui features like zkLogin or sponsored transactions require external infrastructure

For testing features that depend on real validator behavior, use the Sui testnet instead. The setup process is identical - just change the SUI_NETWORK variable to the testnet endpoint (see the Sui documentation for the current URL).

Back to sui & aptos