How to Use `forc update` to Manage Dependencies in Sway

forc update resolves the newest compatible versions of all dependencies in your Sway project and writes the results to Forc.lock, ensuring reproducible builds across environments.

The forc update command is the primary dependency management tool in the Sway ecosystem from FuelLabs. It walks the entire dependency graph defined in your Forc.toml, fetches the latest compatible versions from git, IPFS, local paths, or the community registry, and generates a deterministic lock file that pins every dependency to a specific version.

Core Functionality of forc update

The implementation lives in forc/src/ops/forc_update.rs. When executed, the command performs four critical operations:

1. Load the manifest – Parses the current Forc.toml to identify declared dependencies.
2. Build the dependency graph – Constructs a BuildPlan that resolves the newest compatible versions across all sources.
3. Generate a new lock file – Creates a fresh lock representation from the resolved graph.
4. Diff and persist – Compares the new lock against the existing Forc.lock using new_lock.diff(&old_lock) and writes the changes to disk.

// Simplified flow from forc/src/ops/forc_update.rs
let build_plan = BuildPlan::from_manifest(&manifest)?;
let new_lock = Lock::from_graph(&build_plan.graph);
let diff = new_lock.diff(&old_lock);

Dependency Source Handling

forc update supports four distinct dependency sources, each with specific update semantics:

• Git repositories – If your Forc.toml references a branch (e.g., branch = "master"), forc update fetches the latest commit on that branch and updates the lock. Tags are treated as immutable references and remain unchanged.
• IPFS – Content-addressed dependencies are immutable by design, so the command has no effect on IPFS sources.
• Local paths – Path-based dependencies are also immutable from the lock file perspective; updates require manual changes to Forc.toml.
• Registry (forc.pub) – The community registry follows semantic versioning, and forc update resolves to the latest compatible version based on the version constraints in your manifest.

Command-Line Options for forc update

The CLI definition resides in forc/src/cli/commands/update.rs. The command accepts several flags to control its behavior:

• -d <DEP> / --target_dependency – Restricts the update to a single named dependency, leaving all others pinned to their current versions.
• --check – Performs a dry-run that prints the diff between the current and proposed lock files without writing to Forc.lock. Useful for CI pipelines to detect outdated dependencies.
• --ipfs-node <NODE> – Specifies the IPFS gateway to use when resolving IPFS-based dependencies (options: PUBLIC, LOCAL, or a custom URL).

# Update all dependencies to their latest compatible versions

forc update

# Preview changes without modifying Forc.lock

forc update --check

# Update only the standard library

forc update -d std

# Use a specific IPFS node

forc update --ipfs-node PUBLIC

Automatic Execution During Builds

forc build implicitly invokes forc update logic when no Forc.lock file exists in the project directory. This ensures that fresh clones or new projects always generate a lock file before compilation begins, preventing non-deterministic builds. However, if a lock file already exists, forc build respects the pinned versions and does not automatically update them.

Summary

• forc update resolves the newest compatible dependency versions and writes them to Forc.lock.
• The core implementation is in forc/src/ops/forc_update.rs, which uses BuildPlan and lock diffing to determine changes.
• Git branches are updated to the latest commit, while tags, IPFS, and local paths remain immutable.
• Use --check for dry-runs, -d for targeted updates, and --ipfs-node to configure IPFS resolution.
• forc build automatically generates a lock file if none exists, ensuring reproducible builds from the start.

Frequently Asked Questions

What is the difference between forc update and forc build?

forc update explicitly refreshes the dependency graph and writes a new Forc.lock file, whereas forc build compiles the project using the versions pinned in the existing lock file. If no lock file exists, forc build will generate one automatically before compiling, effectively running an implicit update.

Does forc update modify my Forc.toml file?

No, forc update only modifies the Forc.lock file. It respects the version constraints and source specifications defined in Forc.toml (such as git branches, tags, or registry version ranges) but updates the exact pinned versions in the lock file to the latest compatible versions available at runtime.

How do I preview dependency changes without updating the lock file?

Use the --check flag. This performs a dry-run that calculates the new dependency graph, diffs it against the current Forc.lock, and prints the changes to stdout without writing any files. This is particularly useful in CI pipelines to detect outdated dependencies before they affect the build.

Why didn't forc update change my git tag dependency?

Git tags are treated as immutable references in Sway's dependency system. When you specify a tag in Forc.toml, forc update recognizes that the content addressed by that tag cannot change, so it leaves the pinned version in Forc.lock unchanged. To update to a newer version, you must modify the tag reference in Forc.toml manually.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}