Using CLI to Run a Local Testnet
If you want to use Docker or
aptos-core source to start and run a local testnet, see Run a Local Testnet with Validator.
You can run a local testnet of the Aptos blockchain. This local testnet will not be connected to the Aptos devnet. It will run on your local machine, independent of other Aptos networks. You can use this local testnet for testing and development purposes. A local testnet is a great tool for doing local development against a known version of the codebase without having to interact with a live network or deal with the real world costs of a live network.
If you are new to Aptos CLI, then see this comprehensive Aptos CLI documentation.
Starting a local testnet with a faucet
You can start a local testnet using the following Aptos CLI command:
aptos node run-local-testnet --with-faucet
The above command will start a local validator node and will display a terminal output similar to the following:
Completed generating configuration:
Log file: "/Users/greg/.aptos/testnet/validator.log"
Test dir: "/Users/greg/.aptos/testnet"
Aptos root key path: "/Users/greg/.aptos/testnet/mint.key"
REST API endpoint: 0.0.0.0:8080
Fullnode network: /ip4/0.0.0.0/tcp/6181
Aptos is running, press ctrl-c to exit
Faucet is running. Faucet endpoint: 0.0.0.0:8081
The above command will use the default configuration for the validator node.
Note that two instances of the same command cannot run at the same time. This will result in a conflict on ports for the validator node.
Test with your local testnet
You can use the Aptos CLI for a full range of local testnet operations. See below for how to configure the CLI first.
Configuring your Aptos CLI to use the local testnet
You can add a separate profile, as shown below:
aptos init --profile local --rest-url http://localhost:8080 --faucet-url http://localhost:8081
and you will get an output like below. At the
Enter your private key... command prompt press enter to generate a random new key.
Configuring for profile local
Using command line argument for rest URL http://localhost:8080/
Using command line argument for faucet URL http://localhost:8081/
Enter your private key as a hex literal (0x...) [Current: None | No input: Generate new key (or keep one if present)]
This will create a new account and fund it with the default amount of coins, as shown below:
No key given, generating key...
Account 7100C5295ED4F9F39DCC28D309654E291845984518307D3E2FE00AEA5F8CACC1 doesn't exist, creating it and funding it with 10000 coins
Aptos is now set up for account 7100C5295ED4F9F39DCC28D309654E291845984518307D3E2FE00AEA5F8CACC1! Run `aptos help` for more information about commands
From now on you should add
--profile local to the commands to run them on the local testnet.
Creating and funding accounts
To create new accounts on the local testnet, we recommend using the above instructions with different profile names:
aptos init --profile $PROFILE --rest-url http://localhost:8080 --faucet-url http://localhost:8081
To fund accounts:
aptos account fund --profile $PROFILE --account $PROFILE
To create resource accounts:
aptos account create-resource-account --profile $PROFILE --seed 1
Publishing modules to the local testnet
You can run any command by adding the
--profile $PROFILE flag. In this case, we also use
$PROFILE as the named address in the
aptos move publish --profile $PROFILE --package-dir /opt/git/aptos-core/aptos-move/move-examples/hello_blockchain --named-addresses HelloBlockchain=$PROFILE
"vm_status": "Executed successfully"
Resetting the local state
If you updated your codebase with backwards incompatible changes, or just want to start over, you can run
the command with the
aptos node run-local-testnet --with-faucet --force-restart
It will then prompt you if you really want to restart the chain, to ensure that you do not delete your work by accident.
Are you sure you want to delete the existing chain? [yes/no] >
I'm getting the error
address already in use, what can I do?
If you're getting an error similar to this error:
'panicked at 'error binding to 0.0.0.0:9101: error creating server listener: Address already in use (os error 48)'
This means you are either already running a node, or you have another process running on that port.
On macOS and Linux, you can run the following command to get the name and PID of the process using the port:
lsof -i :$PORT
Where can I get more information about the run-local-testnet command?
More CLI help can be found by running the command:
aptos node run-local-testnet --help
which will provide information about each of the flags for the command.