python: implement PEP 668 (#229166)

Add a marker file to the python outputs that tells pip and other tooling
following PEP 668 that they should not be installing things system-wide.

This provides better feedback to the user and also potentially avoids issues in
single-user installs where the /nix/store is owned by the user.

For more details, see <https://peps.python.org/pep-0668/>

Here is how it currently looks like:

    $ pip install requests
    error: externally-managed-environment

    × This environment is externally managed
    ╰─> This command has been disabled as it tries to modify the immutable
        `/nix/store` filesystem.

        To use Python with Nix and nixpkgs, have a look at the online documentation:
        <https://nixos.org/manual/nixpkgs/stable/#python>.

2 files changed, 12 insertions, 0 deletions

diff --git a/nixos/doc/manual/release-notes/rl-2305.section.md b/nixos/doc/manual/release-notes/rl-2305.section.md
index e937f756991a0..3d5dea7d88564 100644
--- a/nixos/doc/manual/release-notes/rl-2305.section.md
+++ b/nixos/doc/manual/release-notes/rl-2305.section.md
@@ -24,6 +24,8 @@ In addition to numerous new and upgraded packages, this release has the followin
 
 - KDE Plasma has been updated to v5.27, see [the release notes](https://kde.org/announcements/plasma/5/5.27.0/) for what is changed.
 
+- Python implements [PEP 668](https://peps.python.org/pep-0668/), providing better feedback to users that try to run `pip install` system-wide.
+
 - `nixos-rebuild` now supports an extra `--specialisation` option that can be used to change specialisation for `switch` and `test` commands.
 
 - `libxcrypt`, the library providing the `crypt(3)` password hashing function, is now built without support for algorithms not flagged [`strong`](https://github.com/besser82/libxcrypt/blob/v4.4.33/lib/hashes.conf#L48). This affects the availability of password hashing algorithms used for system login (`login(1)`, `passwd(1)`), but also Apache2 Basic-Auth, Samba, OpenLDAP, Dovecot, and [many other packages](https://github.com/search?q=repo%3ANixOS%2Fnixpkgs%20libxcrypt&type=code).
diff --git a/pkgs/development/interpreters/python/cpython/default.nix b/pkgs/development/interpreters/python/cpython/default.nix
index 3f48b2c6eb205..a089dbf2002b9 100644
--- a/pkgs/development/interpreters/python/cpython/default.nix
+++ b/pkgs/development/interpreters/python/cpython/default.nix
@@ -486,6 +486,16 @@ in with passthru; stdenv.mkDerivation {
     # bytecode compilations for the same reason - we don't want bytecode generated.
     mkdir -p $out/share/gdb
     sed '/^#!/d' Tools/gdb/libpython.py > $out/share/gdb/libpython.py
+
+    # Disable system-wide pip installation. See https://peps.python.org/pep-0668/.
+    cat <<'EXTERNALLY_MANAGED' > $out/lib/${libPrefix}/EXTERNALLY-MANAGED
+    [externally-managed]
+    Error=This command has been disabled as it tries to modify the immutable
+     `/nix/store` filesystem.
+
+     To use Python with Nix and nixpkgs, have a look at the online documentation:
+     <https://nixos.org/manual/nixpkgs/stable/#python>.
+    EXTERNALLY_MANAGED
   '';
 
   preFixup = lib.optionalString (stdenv.hostPlatform != stdenv.buildPlatform) ''