From 31110f35d92ea8dfcae14d7a8897d6a89277640d Mon Sep 17 00:00:00 2001
From: Eric Eastwood <erice@element.io>
Date: Wed, 26 Mar 2025 14:35:54 -0500
Subject: [PATCH] Add docs for how to clear out the Poetry wheel cache (#18283)

As shared by @reivilibre,
https://github.com/element-hq/synapse/pull/18261#issuecomment-2754607816

Relevant Poetry issue around how this should be handled by them:
https://github.com/python-poetry/poetry/issues/10304
---
 changelog.d/18283.doc            |  1 +
 docs/development/dependencies.md | 22 ++++++++++++++++++++++
 2 files changed, 23 insertions(+)
 create mode 100644 changelog.d/18283.doc

diff --git a/changelog.d/18283.doc b/changelog.d/18283.doc
new file mode 100644
index 0000000000..77fa08fa6b
--- /dev/null
+++ b/changelog.d/18283.doc
@@ -0,0 +1 @@
+Add docs for how to clear out the Poetry wheel cache.
diff --git a/docs/development/dependencies.md b/docs/development/dependencies.md
index 8e29ff3a57..fa5ff4dcf7 100644
--- a/docs/development/dependencies.md
+++ b/docs/development/dependencies.md
@@ -150,6 +150,28 @@ $ poetry shell
 $ poetry install --extras all
 ```
 
+If you want to go even further and remove the Poetry caches:
+
+```shell
+# Find your Poetry cache directory
+# Docs: https://github.com/python-poetry/poetry/blob/main/docs/configuration.md#cache-directory
+$ poetry config cache-dir
+
+# Remove packages from all cached repositories
+$ poetry cache clear --all .
+
+# Go completely nuclear and clear out everything Poetry cache related
+# including the wheel artifacts which is not covered by the above command
+# (see https://github.com/python-poetry/poetry/issues/10304)
+#
+# This is necessary in order to rebuild or fetch new wheels. For example, if you update
+# the `icu` library in on your system, you will need to rebuild the PyICU Python package
+# in order to incorporate the correct dynamically linked library locations otherwise you
+# will run into errors like: `ImportError: libicui18n.so.75: cannot open shared object file: No such file or directory`
+$ rm -rf $(poetry config cache-dir)
+```
+
+
 ## ...run a command in the `poetry` virtualenv?
 
 Use `poetry run cmd args` when you need the python virtualenv context.