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

> Learn to manage Sway project dependencies with forc update. This command finds the latest compatible versions and updates Forc.lock for reproducible builds.

- Repository: [Fuel Labs/sway](https://github.com/FuelLabs/sway)
- Tags: how-to-guide
- Published: 2026-03-05

---

**`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`](https://github.com/FuelLabs/sway/blob/main/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`](https://github.com/FuelLabs/sway/blob/main/forc/src/ops/forc_update.rs). When executed, the command performs four critical operations:

1. **Load the manifest** – Parses the current [`Forc.toml`](https://github.com/FuelLabs/sway/blob/main/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.

```rust
// 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`](https://github.com/FuelLabs/sway/blob/main/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`](https://github.com/FuelLabs/sway/blob/main/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`](https://github.com/FuelLabs/sway/blob/main/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).

```bash

# 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`](https://github.com/FuelLabs/sway/blob/main/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`](https://github.com/FuelLabs/sway/blob/main/Forc.toml) file?

No, `forc update` only modifies the `Forc.lock` file. It respects the version constraints and source specifications defined in [`Forc.toml`](https://github.com/FuelLabs/sway/blob/main/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`](https://github.com/FuelLabs/sway/blob/main/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`](https://github.com/FuelLabs/sway/blob/main/Forc.toml) manually.