From 31f1a9c5acbf5cec5dfe66882a4945cc1c4d45ca Mon Sep 17 00:00:00 2001
From: Damian Glowala <damian.glowala.rebkow@gmail.com>
Date: Thu, 26 Feb 2026 14:53:06 +0100
Subject: [PATCH 1/2] docs: add sharp cross-platform installation section

---
 docs/content/1.get-started/1.installation.md | 90 +++++++++++++++-----
 1 file changed, 68 insertions(+), 22 deletions(-)

diff --git a/docs/content/1.get-started/1.installation.md b/docs/content/1.get-started/1.installation.md
index 95a861477..26f6c50c5 100644
--- a/docs/content/1.get-started/1.installation.md
+++ b/docs/content/1.get-started/1.installation.md
@@ -20,6 +20,7 @@ npx nuxt module add image
 Add `@nuxt/image` dependency to your project:
 
 ::code-group
+
 ```bash [npm]
 npm i @nuxt/image
 ```
@@ -35,18 +36,62 @@ pnpm add @nuxt/image
 ```bash [bun]
 bun add @nuxt/image
 ```
+
 ::
 
 Then, add it to the `modules` in your `nuxt.config`:
 
 ```ts [nuxt.config.ts]
 export default defineNuxtConfig({
-  modules: [
-    '@nuxt/image'
-  ]
+  modules: ['@nuxt/image']
 })
 ```
 
+## Sharp Cross-Platform Installation
+
+The default [IPX](/providers/ipx) provider uses [sharp](https://sharp.pixelplumbing.com) for image processing. At install time, your package manager downloads prebuilt sharp binaries **only for your current OS and CPU architecture**. This means if you build on macOS or Windows and deploy to a Linux server (or build on x64 and deploy to ARM64), the required sharp binaries might be missing, resulting in errors like:
+
+```
+[500] [IPX_ERROR] Could not load the "sharp" module using the linux-x64 runtime
+```
+
+To fix this, configure your package manager to install sharp binaries for **all target platforms**, e.g.:
+
+::code-group
+
+```json [pnpm (package.json)]
+{
+  "pnpm": {
+    "supportedArchitectures": {
+      "os": ["current", "linux"],
+      "cpu": ["current", "x64", "arm64"]
+    }
+  }
+}
+```
+
+```yaml [yarn (.yarnrc.yml, v3+ only)]
+supportedArchitectures:
+  os:
+    - current
+    - linux
+  cpu:
+    - current
+    - x64
+    - arm64
+```
+
+```bash [npm]
+npm install --cpu=x64 --os=linux sharp
+npm install --cpu=arm64 --os=linux sharp
+```
+
+::
+
+After updating the configuration, reinstall dependencies to download the additional platform binaries.
+
+For more details, see the [sharp cross-platform documentation](https://sharp.pixelplumbing.com/install/#cross-platform).
+
 ## Configuration
 
 Add an `image` section in your `nuxt.config`:
@@ -108,33 +153,34 @@ If an error occurs during installation:
 - Ensure using LTS version of NodeJS ([NodeJS Download page](https://nodejs.org/en/download))
 - Try to upgrade to latest versions:
 
-::div
-  :::code-group
-  ```bash [npm]
-  npm up @nuxt/image
-  ```
-  
-  ```bash [yarn]
-  yarn upgrade @nuxt/image
-  ```
-  
-  ```bash [pnpm]
-  pnpm up @nuxt/image
-  ```
-  
-  ```bash [bun]
-  bun update @nuxt/image
-  ```
-  :::
+::code-group
+
+```bash [npm]
+npm up @nuxt/image
+```
+
+```bash [yarn]
+yarn upgrade @nuxt/image
+```
+
+```bash [pnpm]
+pnpm up @nuxt/image
+```
+
+```bash [bun]
+bun update @nuxt/image
+```
+
 ::
 
 - Try recreating lockfile:
 
 ::div
+
 ```bash
 npx nuxt upgrade --force
 ```
+
 ::
 
-- If there is still an error related to `sharp` and `node-gyp`, it is probably because your OS architecture or NodeJS version is not included in pre-built binaries and needs to be built from source (for example, this sometimes occurs on Apple M1). Checkout [node-gyp](https://github.com/nodejs/node-gyp#installation) for install requirements.
 - If none of the above worked, please [open an issue](https://github.com/nuxt/image/issues) and include error trace, OS, Node version and the package manager used for installing.

From 60353010e548e848e78cc25145696cf1a4d6b6e4 Mon Sep 17 00:00:00 2001
From: Damian Glowala <damian.glowala.rebkow@gmail.com>
Date: Thu, 26 Feb 2026 14:55:07 +0100
Subject: [PATCH 2/2] revert formatting

---
 docs/content/1.get-started/1.installation.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/docs/content/1.get-started/1.installation.md b/docs/content/1.get-started/1.installation.md
index 26f6c50c5..8686d24b0 100644
--- a/docs/content/1.get-started/1.installation.md
+++ b/docs/content/1.get-started/1.installation.md
@@ -43,7 +43,9 @@ Then, add it to the `modules` in your `nuxt.config`:
 
 ```ts [nuxt.config.ts]
 export default defineNuxtConfig({
-  modules: ['@nuxt/image']
+  modules: [
+    '@nuxt/image'
+  ]
 })
 ```