Skip to main content

Updating the Sandbox


Aztec tools (sandbox, nargo), dependencies (aztec-nr), and sample contracts are constantly being improved. When developing and referring to example .nr files/snippets, it is helpful to verify the versions of different components (below), and if required keep them in lock-step by updating.

Checking tool versions


The aztec-nargo versions follow nargo versions, which is different to the Aztec tool versions.

The latest version of the Aztec tooling is currently aztec-packages-v0.43.0 , updating roughly every week.

Dependency versions

Dependency versions in a contract's Nargo.toml file correspond to the aztec-packages repository tag aztec-packages (filter tags by aztec...)

If you get an error like: Cannot read file ~/nargo/ Check the git= github url, tag, and directory.


The folder structure changed at 0.24.0 from yarn-project/aztec-nr to noir-projects/aztec-nr. More details here

Example contract versions

Example contracts serve as a helpful reference between versions of the aztec-nr framework since they are strictly maintained with each release.

Code referenced in the documentation is sourced from contracts within this directory.

As in the previous section, the location of the noir contracts moved at version 0.24.0, from yarn-project/noir-contracts before, to noir-projects/noir-contracts.


Notice the difference between the sample Counter contract from 0.23.0 to 0.24.0 shows the note_type_id was added.

diff ~/nargo/ ~/nargo/
> note_type_id: Field,

Language server version (aztec-nargo)

The Noir LSP uses your local version of aztec-nargo, and thus also aztec-nargo compile. The path of the former (once installed) can be seen by hovering over "Nargo" in the bottom status bar of VS Code, and the latter via the which aztec-nargo command.


For Aztec contract files, this should be aztec-nargo and for noir-only files this should be nargo. Mismatching tools and file types will generate misleading syntax and compiler errors.

This can present confusion when opening older contracts (and dependencies) written in older version of noir, such as:

  • Logs filled with errors from the dependencies
  • Or the LSP fails (re-runs automatically then stops) The second point requires a restart of the extension, which you can trigger with the command palette (Ctrl + Shift + P) and typing "Reload Window".


Steps to keep up to date

  1. Update the Aztec sandbox to the latest version (includes aztec-nargo, pxe, etc):

To set VERSION for a particular git tag, eg for aztec-package-v0.35.0

VERSION=0.35.0 aztec-up
  1. Update aztec-nr and individual @aztec dependencies:

Inside your project run:

cd your/aztec/project
aztec-builder update . --contract src/contract1 --contract src/contract2

The sandbox must be running for the update command to work. Make sure it is installed and running.

Follow updating packages and updating JavaScript packages guides.

  1. Refer to Migration Notes on any breaking changes that might affect your dapp

There are four components whose versions need to be kept compatible:

  1. Aztec Sandbox
  2. aztec-nargo
  3., the Noir framework for writing Aztec contracts

First three are packaged together in docker and are kept compatible by running aztec-up. But you need to update your version manually or using aztec-builder update.

Updating packages

Automatic update

aztec-builder will update your packages to the appropriate version with the aztec-builder update command. Run this command from the root of your project and pass the paths to the folders containing the Nargo.toml files for your projects like so:

aztec-builder update . --contract src/contract1 --contract src/contract2

Manual update

To update the packages manually, update the tags of the dependencies in the Nargo.toml file.

-aztec = { git="", tag="aztec-packages-v0.7.5", directory="noir-projects/aztec-nr/aztec" }
+aztec = { git="", tag="aztec-packages-v0.43.0", directory="noir-projects/aztec-nr/aztec" }
-value_note = { git="", tag="aztec-packages-v0.7.5", directory="noir-projects/aztec-nr/value-note" }
+value_note = { git="", tag="aztec-packages-v0.43.0", directory="noir-projects/aztec-nr/value-note" }

Go to the contract directory and try compiling it with aztec-nargo compile to verify that the update was successful:

cd /your/contract/directory
aztec-nargo compile

If the dependencies fail to resolve ensure that the tag matches a tag in the aztec-packages repository.

Updating Aztec.js packages

To update Aztec.js packages, go to your package.json and replace the versions in the dependencies.

-"@aztec/accounts": "0.7.5",
+"@aztec/accounts": "0.43.0",
-"@aztec/noir-contracts.js": "0.35.1",
+"@aztec/accounts": "0.43.0",

Updating aztec-nargo

As mentioned in the tl;dr, aztec-nargo is updated as part of updating the whole sandbox via:


The version of aztec-nargo that comes with a particular version of the Aztec sandbox can be seen in the monorepo. Eg tag: aztec-packages-v0.35.0 contains aztec-nargo v0.27.0.

Set VERSION to specify the desired Aztec sandbox version, eg monorepo tag suffix 0.35.0 (to have aztec-nargo v0.27.0).

VERSION=<tag-suffix> aztec-up

Note: Being under highly active development it is NOT recommended to specify, master, due to the increased effort to align tooling, dependencies, and example code syntax.