From 93edd0932e636252528ca4b95802f35b1a513b6e Mon Sep 17 00:00:00 2001
From: kegsay <7190048+kegsay@users.noreply.github.com>
Date: Tue, 6 Feb 2024 09:27:38 +0000
Subject: [PATCH] Update docs for MacOS installs (#16854)

ICU is an optional dependency and also a pain to install. Mention that
you can just not install it and still get a working installation.
---
 changelog.d/16854.doc      |  1 +
 docs/setup/installation.md | 11 +++++++++++
 2 files changed, 12 insertions(+)
 create mode 100644 changelog.d/16854.doc

diff --git a/changelog.d/16854.doc b/changelog.d/16854.doc
new file mode 100644
index 000000000..f08a5f4be
--- /dev/null
+++ b/changelog.d/16854.doc
@@ -0,0 +1 @@
+Update MacOS installation instructions to mention that libicu is optional.
diff --git a/docs/setup/installation.md b/docs/setup/installation.md
index fb64c9ba4..324cdc67b 100644
--- a/docs/setup/installation.md
+++ b/docs/setup/installation.md
@@ -326,6 +326,17 @@ Some extra dependencies may be needed. You can use Homebrew (https://brew.sh) fo
 You may need to install icu, and make the icu binaries and libraries accessible.
 Please follow [the official instructions of PyICU](https://pypi.org/project/PyICU/) to do so.
 
+If you're struggling to get icu discovered, and see:
+```
+  RuntimeError:
+  Please install pkg-config on your system or set the ICU_VERSION environment
+  variable to the version of ICU you have installed.
+```
+despite it being installed and having your `PATH` updated, you can omit this dependency by
+not specifying `--extras all` to `poetry`. If using postgres, you can install Synapse via
+`poetry install --extras saml2 --extras oidc --extras postgres --extras opentracing --extras redis --extras sentry`.
+ICU is not a hard dependency on getting a working installation.
+
 On ARM-based Macs you may also need to install libjpeg and libpq:
 ```sh
  brew install jpeg libpq