From 90cd786c2d39d42ebe3d7fb287b96d874aa89052 Mon Sep 17 00:00:00 2001
From: Axel Kohlmeyer <akohlmey@gmail.com>
Date: Tue, 18 Mar 2025 20:20:56 -0400
Subject: [PATCH] document how to address "externally managed environment"
 errors with install-python

---
 doc/src/Build_settings.rst |  2 +-
 doc/src/Howto_python.rst   | 31 +++++++++++++++++++++++++++----
 doc/src/Python_install.rst |  4 ++++
 3 files changed, 32 insertions(+), 5 deletions(-)

diff --git a/doc/src/Build_settings.rst b/doc/src/Build_settings.rst
index acb9aa7535..3f956d551d 100644
--- a/doc/src/Build_settings.rst
+++ b/doc/src/Build_settings.rst
@@ -566,7 +566,7 @@ folder as examples of how those kinds of potential files look like and
 for use with the provided input examples in the ``examples`` tree.  To
 keep the size of the distributed LAMMPS source package small, very large
 potential files (> 5 MByte) are not bundled, but only downloaded on
-demand when the :doc:`corresponding package <Package_list>` is
+demand when the :doc:`corresponding package <Packages_list>` is
 installed.  This automatic download can be prevented when :doc:`building
 LAMMPS with CMake <Build_cmake>` by adding the setting `-D
 DOWNLOAD_POTENTIALS=off` when configuring.
diff --git a/doc/src/Howto_python.rst b/doc/src/Howto_python.rst
index bfb182d989..ee919e96e7 100644
--- a/doc/src/Howto_python.rst
+++ b/doc/src/Howto_python.rst
@@ -62,17 +62,17 @@ with :ref:`PNG, JPEG and FFMPEG output support <graphics>` enabled.
 
          cd $LAMMPS_DIR/src
 
-         # add packages if necessary
+         # add LAMMPS packages if necessary
          make yes-MOLECULE
          make yes-PYTHON
 
          # compile shared library using Makefile
          make mpi mode=shlib LMP_INC="-DLAMMPS_PNG -DLAMMPS_JPEG -DLAMMPS_FFMPEG" JPG_LIB="-lpng -ljpeg"
 
-Step 2: Installing the LAMMPS Python package
-""""""""""""""""""""""""""""""""""""""""""""
+Step 2: Installing the LAMMPS Python module
+"""""""""""""""""""""""""""""""""""""""""""
 
-Next install the LAMMPS Python package into your current Python installation with:
+Next install the LAMMPS Python module into your current Python installation with:
 
 .. code-block:: bash
 
@@ -89,6 +89,29 @@ privileges) or into your personal Python module folder.
    Recompiling the shared library requires re-installing the Python
    package.
 
+.. _externally_managed:
+
+.. admonition:: Handling an "externally-managed-environment" Error
+   :class: Hint
+
+   Some Python installations made through Linux distributions
+   (e.g. Ubuntu 24.04LTS or later) will prevent installing the LAMMPS
+   Python module into a system folder or a corresponding folder of the
+   individual user as attempted by ``make install-python`` with an error
+   stating that an *externally managed* python installation must be only
+   managed by the same package package management tool.  This is an
+   optional setting, so not all Linux distributions follow it currently
+   (Spring 2025).  The reasoning and explanations for this error can be
+   found in the `Python Packaging User Guide
+   <https://packaging.python.org/en/latest/specifications/externally-managed-environments/>`_
+
+   These guidelines suggest to create a virtual environment and install
+   the LAMMPS Python module there (see below).  This is generally a good
+   idea and the LAMMPS developers recommend this, too.  If, however, you
+   want to proceed and install the LAMMPS Python module regardless, you
+   can install the "wheel" file (see above) manually with the ``pip``
+   command by adding the ``--break-system-packages`` flag.
+
 Installation inside of a virtual environment
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
diff --git a/doc/src/Python_install.rst b/doc/src/Python_install.rst
index 1e53a99914..561e4a2f92 100644
--- a/doc/src/Python_install.rst
+++ b/doc/src/Python_install.rst
@@ -198,6 +198,10 @@ folder that the dynamic loader searches or inside of the installed
 
          The ``PYTHONPATH`` needs to point to the parent folder that contains the ``lammps`` package!
 
+In case you run into an "externally-managed-environment" error when
+trying to install the LAMMPS Python module, please refer to
+:ref:`corresponding paragraph <externally_managed>` in the Python HOWTO
+page to learn about options for handling this error.
 
 To verify if LAMMPS can be successfully started from Python, start the
 Python interpreter, load the ``lammps`` Python module and create a