Anchor Local Setup

This lesson has one job.

Get you to a working Anchor workspace that builds and tests locally without mystery.

If this part is shaky, every later lesson turns into environment debugging.

The Goal

By the end of this lesson, you should be able to:

• verify that Rust, Solana CLI, and Anchor CLI are installed
• create a new Anchor workspace
• run anchor build
• run anchor test
• explain what those two commands actually do

That is enough for the first step.

The Current Installation Path

The official Solana docs now provide a one-command installer that sets up the standard local toolchain.

curl --proto '=https' --tlsv1.2 -sSfL https://solana-install.solana.workers.dev | bash

That is the fastest way to get the full environment onto your machine.

After the install finishes, restart your terminal.

Then verify the tools actually exist:

rustc --version
solana --version
anchor --version
node --version
yarn --version

Why this matters:

• Rust compiles your program
• Solana CLI manages wallets, clusters, and validator commands
• Anchor CLI creates, builds, deploys, and tests Anchor workspaces
• Node and Yarn are needed for the default TypeScript test template created by anchor init

When To Use AVM

If you only want a fast first setup, the installer above is enough.

If you expect to work across multiple Anchor projects, install AVM as well.

cargo install --git https://github.com/coral-xyz/anchor avm --force
avm --version
avm install latest
avm use latest
anchor --version

What AVM changes:

• you can pin a specific Anchor version per machine workflow
• switching Anchor versions stops being manual
• reproducing an older project becomes much easier

You do not need to overthink this yet.

Just remember the rule: if version drift becomes a problem, use AVM.

Create Your First Workspace

Now create a project.

anchor init anchor_starter
cd anchor_starter

This gives you a default Anchor workspace with:

• Anchor.toml for project configuration
• programs/ for on-chain Rust code
• tests/ for integration tests
• migrations/ for deployment scripting
• target/ after builds

If you want Rust-based tests instead of the default TypeScript template, Anchor now supports that directly at project creation time:

anchor init --test-template rust anchor_starter_rust

For this curriculum, the default test template is fine for the first setup pass.

The goal right now is not to choose the perfect test stack.

The goal is to get one clean loop working.

Look At Anchor.toml Before You Run Anything

Open Anchor.toml once.

You are looking for one thing first: the cluster configuration.

In a new local project, you generally want to stay on localnet while learning.

That matters because anchor test behaves differently depending on the configured cluster.

When the workspace is set to localnet, Anchor can:

• start a local validator
• deploy your program into that local validator
• run your tests
• shut the validator down after the test run

That is your main learning loop.

Run anchor build First

Do not jump straight to tests.

Build first.

anchor build

What this does:

• compiles your Rust program
• generates build artifacts in target/
• updates the IDL output for your program

If anchor build fails, that usually means one of these is wrong:

• Rust toolchain
• Anchor installation
• local dependency setup
• workspace configuration

Fix build issues before you move to tests.

Run anchor test

Once the build works, run:

anchor test

What this does in the normal local workflow:

• builds the workspace
• starts localnet if needed
• deploys your program locally
• runs the generated integration tests

If this passes, your setup is good enough for the rest of the section.

That is the baseline you want.

What Success Looks Like

A successful setup means all of these are true:

• anchor --version works
• anchor init created the workspace without errors
• anchor build finishes successfully
• anchor test finishes successfully
• you understand where the program code and tests live

If one of those is missing, you are not fully set up yet.

Common Failures And The Real Cause

anchor: command not found

Your shell cannot find the Anchor binary.

Check:

anchor --version
avm --version

If AVM is installed but anchor is missing, restart your terminal and run:

avm use latest

could not exec the linker cc

The Anchor docs call this out on Linux and WSL.

This usually means system build dependencies are missing or not available to the Rust toolchain.

The right fix is not random cargo commands.

The right fix is to install the missing Linux dependencies and then retry the Anchor install.

anchor test fails before tests run

Do not assume your program logic is wrong.

Very often the problem is one of these:

• another local validator is already running
• Node or Yarn is missing for the default test template
• the workspace did not build cleanly first

The official CLI docs note that anchor test can fail if another local validator is already running.

If that happens, shut it down and rerun the test.

Wallet or keypair problems

If Solana CLI is installed but your keypair setup is missing, create one:

solana-keygen new
solana address

You do not need devnet SOL for the local test flow.

For localnet, the validator controls the test environment.

What To Check In The Generated Project

Before moving on, open these files once:

• Anchor.toml
• programs/<project-name>/src/lib.rs
• tests/<project-name>.ts

You are not studying the code deeply yet.

You are just building a map of the workspace.

That will matter in the next lesson.

Fast Verification Checklist

Run this sequence in order:

anchor --version
anchor init anchor_starter
cd anchor_starter
anchor build
anchor test

If those commands all work, your local setup is ready.

What You Should Know Before Moving On

Before leaving this lesson, you should be able to answer these two questions clearly:

1. What is the difference between anchor build and anchor test?
2. Why is localnet the safest place to learn first?

If those answers are still fuzzy, rerun the workflow once more.

What Comes Next

The next lesson is not more setup.

It is learning what the generated Anchor workspace actually contains, and why those files exist.