diff --git a/README.md b/README.md
index 722048b3..4678abd8 100644
--- a/README.md
+++ b/README.md
@@ -33,6 +33,8 @@ Then simply run `codex` to get started:
 codex
 ```
 
+If you're running into upgrade issues with Homebrew, see the [FAQ entry on brew upgrade codex](./docs/faq.md#brew-update-codex-isnt-upgrading-me).
+
 <details>
 <summary>You can also go to the <a href="https://github.com/openai/codex/releases/latest">latest GitHub Release</a> and download the appropriate binary for your platform.</summary>
 
diff --git a/docs/faq.md b/docs/faq.md
index 55a6e5e3..6ad0d51e 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -42,3 +42,14 @@ Running Codex directly on Windows may work, but is not officially supported. We
 ### Where should I start after installation?
 
 Follow the quick setup in [Install & build](./install.md) and then jump into [Getting started](./getting-started.md) for interactive usage tips, prompt examples, and AGENTS.md guidance.
+
+### `brew upgrade codex` isn't upgrading me
+
+If you're running Codex v0.46.0 or older, `brew upgrade codex` will not move you to the latest version because we migrated from a Homebrew formula to a cask. To upgrade, uninstall the existing oudated formula and then install the new cask:
+
+```bash
+brew uninstall --formula codex
+brew install --cask codex
+```
+
+After reinstalling, `brew upgrade --cask codex` will keep future releases up to date.