How do I add dependencies to a Sui Move package?

Add a line to the [dependencies] section of Move.toml. The package manager supports four kinds: a Move Registry (MVR) name such as { r.mvr = "@potatoes/ascii" } (recommended for published packages), a git repository, a local path, or a system package. The Sui framework (sui) and standard library (std) are included automatically, so don't add them. The key you choose is the name you use in Move code.

The four dependency types

TOML

[package]
name = "my_app"
edition = "2024"

[dependencies]
# Move Registry: resolves the right address for mainnet or testnet
ascii = { r.mvr = "@potatoes/ascii" }

# Git: repository, subdirectory of the package, and a revision
usdc = { git = "https://github.com/circlefin/stablecoin-sui.git", subdir = "packages/usdc", rev = "master" }

# Local: another package in the same repo
shared = { local = "../shared" }

# System: built-in packages other than std and sui
sui_system = { system = "sui_system" }

Then import modules by the dependency's name:

Move

module my_app::example;

use ascii::char;
use usdc::usdc::USDC;

When you build, the package manager fetches the sources into ~/.move, pins exact versions in Move.lock, and at publish time links to the on-chain package listed in that dependency's Published.toml.

MVR is the preferred way to depend on published packages. You can browse names at moveregistry.com.
Git needs git, subdir (if the package isn't at the repo root) and rev, which can be a branch, a tag or a commit hash. For production builds, use a full 40-character commit hash instead of a branch, which can change under you. Short hashes work but force a full history download.
System packages are std, sui, sui_system, bridge and deepbook. The deepbook system package is the deprecated DeepBook v2. Use DeepBook v3 through MVR instead.

Updating and locking

Terminal

sui move build          # fetches and pins dependencies on first build
sui move update-deps    # re-pins to the latest matching revisions

Commit Move.lock and Published.toml, and never edit Move.lock by hand. Dependencies are only re-pinned when Move.toml changes or you run update-deps.

Different dependencies per network

Builds always target an environment (mainnet and testnet are built in). MVR dependencies pick the right address for each network automatically. For git dependencies, override per network with [dep-replacements.<env>]:

TOML

[dependencies]
codec = { git = "https://github.com/sui-potatoes/app.git", subdir = "packages/codec", rev = "codec@testnet-v2" }

[dep-replacements.mainnet]
codec = { git = "https://github.com/sui-potatoes/app.git", subdir = "packages/codec", rev = "codec@mainnet-v2" }

A replacement must repeat the git field. It isn't merged with the original entry.

Advanced fields

rename-from: depend on two packages that are both called math: math_a = { r.mvr = "@a/math", rename-from = "math" }.
override = true: force one version of a shared transitive dependency when two of your dependencies disagree. You can only override to a newer version.
modes = ["test"]: include a dependency only for sui move test or -m test builds.
published-at / original-id (in [dep-replacements] only): set a dependency's on-chain addresses by hand, for legacy packages that don't ship a proper Published.toml. You have to give both.

Migrating old manifests

Before Sui CLI 1.63, manifests listed Sui = { git = "https://github.com/MystenLabs/sui.git", ... } and had an [addresses] section. To migrate, remove the explicit Sui/MoveStdlib entries and the [addresses] and [dev-addresses] sections. Then rename [package] name and each dependency key to the names your Move code uses (for example, name = "my_package" instead of "MyPackage"), because those names are now the address names in code. Common errors:

Unresolved addresses found: you used a package name in code that isn't in [dependencies].
Failed to resolve dependencies for package: wrong path, typo, or missing Move.toml at the dependency location.

Next: publish the package, or set up VS Code for Move so it resolves dependencies as you type.

Sources

Move Package Management, Sui documentation
Move.toml Manifest Reference, Sui documentation
Package Manager Migration, Sui documentation
Troubleshooting Common Errors, Sui documentation