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.

2 files changed, 12 insertions, 0 deletions

diff --git a/changelog.d/16854.doc b/changelog.d/16854.doc
new file mode 100644

index 0000000000..f08a5f4be2
--- /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 fb64c9ba4d..324cdc67b2 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