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 bytecode, and publish that bytecode as a package object to a Sui network.

How do I publish a package?​

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 CLI resolves the Sui framework automatically, so you do not need an explicit entry for it 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. Estimate gas cost: Run sui client publish --dry-run to estimate gas cost before publishing.
  5. 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.
  6. 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. The UpgradeCap is the object that the initial publish creates, and every upgrade requires it. 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).

How do I upgrade a package?​

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

Which network should I publish to?​

  • 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.

How do I fetch the code of a published package?​

A package on Sui holds compiled Move bytecode, not the original Move source. To inspect what a package (for example, the package that defines a token) contains, generate a bytecode summary from its package ID with the Sui CLI.

  1. Configure the Sui CLI for the network where the package lives. The command requires a configured network and fails without one.
  2. Run sui move summary --package-id with the package ID, and add the --bytecode flag.

The --package-id option only supports bytecode summaries. If you omit --bytecode, the CLI prints a warning and falls back to a bytecode-based summary anyway. Pass --bytecode to avoid the warning.

If you also have a copy of the Move source that claims to match the package, run sui client verify-source from that package directory. The command rebuilds the local source with the toolchain version that originally published the package and compares the result against the onchain bytecode and linkage. A match confirms that the source you hold is the code running onchain.