How to upgrade Homebrew packages

Homebrew upgrades move installed formulae and casks from the versions already on disk to newer versions available in Homebrew metadata. A deliberate upgrade pass matters when command-line tools, desktop apps, and shared dependencies live in the same prefix and a broad update could change more than the one package that needs attention.

A controlled routine refreshes metadata, inspects the outdated package list, previews the upgrade plan, and upgrades the intended package first. Homebrew skips pinned packages during normal upgrades, and a targeted upgrade can still include dependent formulae when they are outdated or have broken linkage.

Use a named package for a narrow change window and reserve a name-free brew upgrade for maintenance periods where every unpinned outdated package is acceptable. The final checks compare Homebrew's installed version and run the upgraded package itself, because disappearing from brew outdated only proves the package is no longer behind according to Homebrew metadata.

Steps to upgrade Homebrew packages:

Refresh Homebrew metadata when the local package list may be stale.
```
$ brew update
Already up-to-date.
```
brew update fetches current Homebrew and tap metadata without upgrading installed packages.
Related: How to update Homebrew package metadata
Check the target package in the outdated list.
```
$ brew outdated --verbose jq
jq (1.8.1) < 1.8.2
```
No output means Homebrew does not currently mark that package as outdated. Omit the package name to review the full outdated set before a broad upgrade.
Confirm that the target package is not pinned.
```
$ brew list --pinned jq
```
No output means jq is not pinned. If the package name is printed, unpin it only after the hold is no longer needed.
Preview the upgrade plan for the package.
```
$ brew upgrade --dry-run jq
==> Would upgrade 1 outdated package
jq  1.8.1 -> 1.8.2 (441KB)
```
--dry-run prints what Homebrew would upgrade without changing installed packages. For a cask token, use brew upgrade --cask visual-studio-code --dry-run.
Upgrade the target package.
```
$ brew upgrade jq
==> Upgrading 1 outdated package:
jq 1.8.1 -> 1.8.2
==> Fetching downloads for: jq
==> Upgrading jq
  1.8.1 -> 1.8.2
##### snipped #####
```
Read any confirmation prompt before continuing. If Homebrew lists unexpected dependents or casks, stop and review the dry-run output again.
Confirm the installed package version.
```
$ brew list --versions jq
jq 1.8.2
```
Recheck the target package in the outdated list.
```
$ brew outdated --verbose jq
```
No output means the package is no longer outdated according to the current Homebrew metadata.
Run a package-specific smoke test.
```
$ jq --version
jq-1.8.2
```
Replace jq --version with the normal command, app launch, service check, or plugin check for the package that was upgraded.