# Update packages {#root}

@status:doc/work @audience:user

[p01] Packages change. This page shows which of yours have a newer version, moves one or all of them forward, and explains what vibe records during the move.

[p02]
```prompt
In the VibeVM project in the current folder, show me which packages have newer versions, then update all of them, and summarise what changed in the lock file.
```

- needs: the vibevm skill installed for your agent; a project with `vibe.toml` and `vibe.lock`; network access to the project's registries

outcome: `vibe outdated` lists the candidates, `vibe update --all` moves the pins, and the diff of `vibe.lock` shows the old and new versions

- assert: `vibe check --quiet`
- assert: `vibe list --quiet`

## What happens {#what-happens}

[p03] The agent first runs `vibe outdated`, which compares every pin in the [lock file](../glossary/index.xml#lock-file) with the newest version the [registry](../glossary/index.xml#registry) offers and prints the difference; it changes nothing. Then it runs `vibe update --all`. vibe re-resolves the graph, preferring the current version of every package that is not being updated, and fetches what is new into the [store](../glossary/index.xml#store). It shows the plan; on confirmation it replaces the package trees, rewrites the lock file and regenerates the boot files. The agent finishes by reading the lock file's diff back to you: that diff is the exact list of text your agent will read differently from now on.

> [p04] `vibe update` remains the explicit "re-resolve and pick newer" command.
>
> <spec://org.vibevm.core/vibevm/modules/vibe-workspace/PROP-011#UPDATE-MOVES-LOCK>

## By hand {#by-hand}

[p05] 1. See what is behind:

[p06]
```sh
vibe outdated --path hello-vibe
```

```output
PACKAGE VERSIONS
GROUP                 NAME                          INSTALLED      LATEST         STATUS
org.vibevm.world      wal                           1.0.0           -               unknown

0 of 1 package have updates available
```

[p07] 2. Update one package, or all of them:

[p08]
```sh
vibe update org.vibevm.world/wal --path hello-vibe --assume-yes
```

```output
Re-resolving 1 package…
  → closure unchanged (1 packages)

Updated 1 package (0 version bumps).
```

[p09] `vibe update --all` updates everything in the lock file; the two forms are mutually exclusive.

[p10] 3. Read the diff of `vibe.lock` before you commit it. Each changed entry names the old and the new version and [fingerprint](../glossary/index.xml#fingerprint).

## The constraint stays where you put it {#the-constraint}

[p11] An update moves the pin in the lock file within the constraint the [manifest](../glossary/index.xml#manifest) names; it never widens or narrows the constraint. If the manifest says `^1.0`, an update will not cross to 2.0 on its own. To move the constraint too, install the new version explicitly with a new constraint, or pass `--exact` to pin the resolved version in the manifest as well.

> [p12] `flow:wal@^0.3` → semver range.
>
> <spec://org.vibevm.core/vibevm/common/PROP-000#CF-RANGE>

## Recovering after a breaking update {#recovery}

[p13] If an update leaves the project in a state that no longer checks, the lock file in version control is your way back. Restore it and run `vibe reinstall`, which rebuilds the tree from the lock and the store without the network. If the store itself holds a damaged entry, `vibe cache check` finds it and `vibe cache clean --package` removes it, after which a fresh install fetches the package again.

> [p14] Without `--force` it recomputes the materialisation and the boot artifacts from the existing `vibe.lock` and the local cache — no fresh resolution.
>
> <spec://org.vibevm.core/vibevm/modules/vibe-workspace/PROP-009#REINSTALL-NO-FORCE>

## Edge cases and rules {#edge-cases}

[p15] `vibe outdated` reads the registries declared in the project's manifest, and for the fastest answer their [index](../glossary/index.xml#index-registry); a project created by `vibe init` declares none, so add one with `vibe registry add` before asking. Without a network it reports what it could not reach rather than guessing.

[p16] A dependency declared as a git branch is walked again on update and its lock entry moves to the branch's current commit; a tag or a commit stays where it is.

> [p17] Mutable branch. Lockfile records the resolved commit at install time; subsequent `vibe update` re-walks branch HEAD. **Mutable** — see "Mutability and `vibe update`" below.
>
> <spec://org.vibevm.core/vibevm/modules/vibe-registry/PROP-002#ROW-GS-BRANCH-MEANING>

[p18] `--upstream` also compares the upstream releases a package declares it describes, for packages that document a third-party library.