From 1ec2ccca14f2bc1a8c8f3ef11a659f9f96407562 Mon Sep 17 00:00:00 2001
From: "James R. Barlow" <james@purplerock.ca>
Date: Fri, 10 Dec 2021 17:42:50 -0800
Subject: [PATCH] docs: add warning about multiproc on macOS

---
 docs/api.rst | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/docs/api.rst b/docs/api.rst
index f3e03534..a6339f38 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -68,6 +68,14 @@ OCRmyPDF, use processes.
     not take at least one of these steps, process semantics will prevent
     OCRmyPDF from working correctly.
 
+.. warning::
+
+    On macOS with Python 3.7, you must call
+    :func:`multiprocessing.set_start_method("spawn")`. Without this, multiprocessing
+    will be unstable. From the command line, OCRmyPDF does this automatically,
+    but as an API user you must do this. See Python bpo-33725 for details.
+    Python 3.8+ also resolve this automatically.
+
 Logging
 -------