diff --git a/README.md b/README.md
index 4409b19..16d63d5 100644
--- a/README.md
+++ b/README.md
@@ -112,6 +112,10 @@ docker run -v /mydir:/app/reports soxoj/maigret:latest username --html
 docker build -t maigret .
 ```
 
+### Troubleshooting
+
+If you encounter build errors during installation, check the [troubleshooting guide](https://maigret.readthedocs.io/en/latest/installation.html#troubleshooting).
+
 ## Usage examples
 
 ```bash
diff --git a/docs/source/installation.rst b/docs/source/installation.rst
index e8fc7bb..d0a5413 100644
--- a/docs/source/installation.rst
+++ b/docs/source/installation.rst
@@ -90,3 +90,39 @@ Docker
 
    # manual build
    docker build -t maigret .
+
+Troubleshooting
+---------------
+
+If you encounter build errors during installation such as ``cannot find ft2build.h``
+or errors related to ``reportlab`` / ``_renderPM``, you need to install system-level
+dependencies required to compile native extensions.
+
+**Debian/Ubuntu/Kali:**
+
+.. code-block:: bash
+
+   sudo apt install -y libfreetype6-dev libjpeg-dev libffi-dev
+
+**Fedora/RHEL/CentOS:**
+
+.. code-block:: bash
+
+   sudo dnf install -y freetype-devel libjpeg-devel libffi-devel
+
+**Arch Linux:**
+
+.. code-block:: bash
+
+   sudo pacman -S freetype2 libjpeg-turbo libffi
+
+**macOS (Homebrew):**
+
+.. code-block:: bash
+
+   brew install freetype
+
+After installing the system dependencies, retry the maigret installation.
+
+If you continue to have issues, consider using Docker instead, which includes all
+necessary dependencies.