Skip to main content

Packages

A Move package on Sui includes one or more modules that define the package's interaction with onchain objects. You develop the logic for those modules in Move, compile them into an object, and publish that package object to a Sui network.

Publish workflow​

Publishing a package follows this sequence:

  1. Write and test your Move code: Create a Move project with sui move new PROJECT_NAME, write your modules, and run tests with sui move test.
  2. Configure your manifest: Verify that your Move.toml uses edition = "2024" and lists all dependencies. The Sui framework is resolved automatically and does not need an explicit entry in [dependencies]. See the Manifest Reference for the full syntax.
  3. Build the package: Run sui move build to compile. Fix any errors before publishing.
  4. Publish to the network: Run sui client publish from the package root. The command compiles, creates a package object onchain, and returns the package ID. You need sufficient gas in your active address. Use --dry-run to estimate gas cost before publishing.
  5. Verify publication: Use sui client verify-source from the package directory to confirm that the onchain bytecode matches your local source.
caution

Publishing is irreversible. Once you publish a package, you cannot delete it from the network. You can upgrade the package if you retain the UpgradeCap, but the original version remains onchain. Store your UpgradeCap in a multisig address or apply a custom upgrade policy for production packages (Security Best Practices).

Upgrade packages​

After publishing, you can deploy new versions of your package using sui client upgrade. Upgrades require the UpgradeCap object that was created during the initial publish. The upgrade policy determines which types of changes are allowed. See the upgrade-specific pages below for details on upgrade policies, compatibility rules, and multisig signing workflows.

Network considerations​

  • Testnet and Devnet: Use these for development and testing. Testnet and Devnet addresses are separate from Mainnet, and packages published on one network do not exist on another.
  • Mainnet: Production deployments. Verify your tests, dependencies, and gas budget before publishing. Use --dry-run to simulate the transaction without committing it.