From 873f915212b1253936ae3c79d7dc737f5c0055ba Mon Sep 17 00:00:00 2001 From: "James R. Barlow" Date: Tue, 9 Mar 2021 23:24:10 -0800 Subject: [PATCH] docs: mention problems with Debian/Ubuntu and other tidying --- docs/installation.rst | 28 ++++++++++++++++++++++++---- 1 file changed, 24 insertions(+), 4 deletions(-) diff --git a/docs/installation.rst b/docs/installation.rst index 4fc3738a..047d4bb5 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -158,7 +158,7 @@ To install ocrmypdf for the system: .. code-block:: bash - sudo pip3 install ocrmypdf + pip3 install ocrmypdf To install for the current user only: @@ -380,12 +380,16 @@ Install the following dependencies: To install ocrmypdf for the system: +.. code-block:: bash + # As root user pip3 install ocrmypdf ldconfig Or, to install for the current user only: +.. code-block:: bash + export PATH=$HOME/.local/bin:$PATH pip3 install --user ocrmypdf @@ -520,7 +524,7 @@ DLLs or other Windows patches, and may require a reboot. You may then use ``pip`` to install ocrmypdf. (This can performed by a user or Administrator.): -* ``pip install ocrmypdf +* ``pip install ocrmypdf`` Chocolatey automatically selects appropriate versions of these applications. If you are installing them manually, please install 64-bit versions of all applications for @@ -536,8 +540,9 @@ to change the PATH. .. warning:: As of early 2021, users have reported problems with the Microsoft Store version of - Python affected most third party Python packages including OCRmyPDF. Please use - Python downloaded from Python.org or Chocolatey as recommended here. + Python and OCRmyPDF. These issues affect many other third party Python packages. + Please download Python from Python.org or Chocolatey instead, and do not use the + Microsoft Store version. Windows Subsystem for Linux --------------------------- @@ -645,6 +650,21 @@ the latest version. However, PyPI and ``pip`` cannot address the fact that ``ocrmypdf`` depends on certain non-Python system libraries and programs being installed. +.. warning:: + + Debian and Ubuntu users: unfortunately, Debian and Ubuntu customize + Python in non-standard ways, and the nature of these customizations + varies from release to release. This can make for a frustrating + user experience. The instructions below work on almost all platforms that + have Python installed, except for Debian and Ubuntu, where you may need + to take additional steps. For best results on Debian and Ubuntu, use the + ``apt`` packages; or if these are too old, run + ``apt install python3-pip python3-venv``, create a virtual environment, + and install OCRmyPDF in that environment. + + `See here for more inforation on Debian-Python issues + `__. + For best results, first install `your platform's version `__ of ``ocrmypdf``, using the instructions elsewhere in this document. Then