@@ -332,6 +332,158 @@ servers where isolation and correctness is more important
 than speed.
 
 
+.. _cache_scopes:
+
+Cache scopes
+------------
+
+.. versionadded:: 9.2
+
+Not everything in the cache is equally portable. Which tests exist, and which are skipped, depends on the
+interpreter running them, so the state behind :option:`--lf`, :option:`--nf` and :option:`--sw <--sw>` is
+only meaningful for the environment that recorded it.
+
+pytest keeps such values apart *within* a single cache directory, rather than needing one cache directory
+per environment. Every cached value has a :class:`~pytest.CacheScope`:
+
+.. list-table::
+   :header-rows: 1
+
+   * - Scope
+     - Valid for
+   * - :attr:`CacheScope.SHARED <pytest.CacheScope.SHARED>`
+     - the project, whatever runs it. The default.
+   * - :attr:`CacheScope.PYTHON <pytest.CacheScope.PYTHON>`
+     - one Python implementation and ``major.minor`` version
+   * - :attr:`CacheScope.ENV <pytest.CacheScope.ENV>`
+     - one environment, i.e. one :data:`sys.prefix`
+
+``--lf``, ``--nf`` and ``--sw`` use ``ENV``. Running a project under a tox or nox matrix, or simply under
+two virtualenvs, therefore no longer has each run overwrite the previous one's last-failed set.
+
+Plugins can do the same:
+
+.. code-block:: python
+
+    def pytest_configure(config):
+        # Valid anywhere the project is.
+        config.cache.set("myplugin/schema-version", 3)
+
+        # Only valid for the environment that collected it.
+        config.cache.set("myplugin/collected", ids, scope=pytest.CacheScope.ENV)
+
+Reads must use the same scope they were written with. ``SHARED`` is the default, so existing plugins keep
+working and keep their existing on-disk location.
+
+
+.. _cache_location:
+
+Where the cache is stored
+-------------------------
+
+.. versionadded:: 9.2
+
+By default the cache lives in ``.pytest_cache`` inside the :ref:`rootdir <rootdir>`. The
+:confval:`cache_policy` option chooses somewhere else by name:
+
+.. code-block:: ini
+
+    [pytest]
+    cache_policy = user
+
+``local``
+    ``<rootdir>/.pytest_cache``. The default.
+
+``user``
+    A directory keyed by project inside the platform's user cache directory - ``$XDG_CACHE_HOME/pytest``
+    or ``~/.cache/pytest`` on Linux, ``~/Library/Caches/pytest`` on macOS, ``%LOCALAPPDATA%\pytest\Cache``
+    on Windows. Nothing at all is written into the project.
+
+    This requires the ``xdg`` extra::
+
+        pip install pytest[xdg]
+
+:confval:`cache_dir` remains available and always wins: it is an explicit path, while ``cache_policy``
+only chooses a location when ``cache_dir`` is unset. Use it for anywhere the two policies do not name -
+it expands environment variables, so a cache inside the current virtualenv is:
+
+.. code-block:: ini
+
+    [pytest]
+    cache_dir = $VIRTUAL_ENV/.pytest_cache
+
+To opt in for a whole machine without editing every project, set the environment variable instead:
+
+.. code-block:: bash
+
+    export PYTEST_CACHE_POLICY=user
+
+An explicit ``cache_policy`` in a config file still wins over it.
+
+Under the ``user`` policy the directory is named after the project and a digest of its path, so it stays
+recognisable::
+
+    ~/.cache/pytest/myproject-1a2b3c4d5e6f7a8b/
+
+The key is the rootdir alone - not the interpreter, which is handled by :ref:`cache scopes <cache_scopes>`
+instead. One project therefore gets one cache directory however many environments run it. A *new*
+directory only appears if the project itself moves.
+
+
+.. _cache_pruning:
+
+Listing and pruning caches
+--------------------------
+
+.. versionadded:: 9.2
+
+A cache stored inside the project is deleted along with the project. One stored under the ``user`` policy
+is not, so pytest can tell you what has accumulated:
+
+.. code-block:: bash
+
+    pytest --cache-list
+
+.. code-block:: text
+
+    user cache directory: /home/ronny/.cache/pytest
+
+      DIRECTORY               SIZE      LAST USED  STATUS    ORIGIN
+      myproject-1a2b3c4d5e6f  12.4 MiB  2 days     ok        /home/ronny/src/myproject
+        env-venv-9f8e7d6c      1.1 MiB  2 days     ok        /home/ronny/src/myproject/.venv
+        env-py312-0a1b2c3d   840.1 KiB  94 days    stale     /home/ronny/src/myproject/.tox/py312
+      oldthing-9f8e7d6c5b4a  840.0 KiB  31 days    orphaned  /home/ronny/src/oldthing
+
+    2 directories, 3 scopes, 13.2 MiB total
+
+``orphaned`` means the origin project no longer exists, and ``stale`` means the environment a scope holds
+state for no longer exists. In terminals which support it, the directory and origin columns are clickable
+links.
+
+Nothing is ever removed automatically. To remove things, say which:
+
+.. code-block:: bash
+
+    pytest --cache-prune=stale       # state for environments that are gone
+    pytest --cache-prune=orphaned    # caches for projects that are gone
+    pytest --cache-prune='oldthing-*'  # by name, or by origin path
+    pytest --cache-prune=all
+
+``--cache-prune`` requires a selector, so a bare invocation cannot delete anything, and it does not ask
+for confirmation once given one - use ``--cache-list`` as the preview. ``all`` never removes the cache
+directory of the project you run it from.
+
+.. note::
+
+    A project on an unmounted network or removable volume looks ``orphaned``, and a virtualenv on one
+    looks ``stale``. This is the main reason pruning is never automatic.
+
+.. note::
+
+    ``--cache-list`` and ``--cache-prune`` only see the user-level cache root. Caches placed somewhere
+    else with :confval:`cache_dir` are not tracked, since pytest has no way to know where they all are.
+
+
 .. _cache stepwise:
 
 Stepwise
 
@@ -457,6 +457,11 @@ Under the hood, the cache plugin uses the simple
 .. autoclass:: pytest.Cache()
    :members:
 
+How far a cached value travels is given by its :class:`pytest.CacheScope`; see :ref:`cache_scopes`.
+
+.. autoclass:: pytest.CacheScope()
+   :members:
+
 
 .. fixture:: doctest_namespace
 
@@ -1215,6 +1220,20 @@ Environment variables that can be used to change pytest's behavior.
    This is not meant to be set by users, but is set by pytest internally with the name of the current test so other
    processes can inspect it, see :ref:`pytest current test env` for more information.
 
+.. envvar:: PYTEST_CACHE_HOME
+
+   Overrides the user-level cache root used by ``cache_policy = user``, instead of asking the platform
+   for it. Useful for a shared, explicit location in CI. See :ref:`cache_location`.
+
+   .. versionadded:: 9.2
+
+.. envvar:: PYTEST_CACHE_POLICY
+
+   Sets the default for :confval:`cache_policy`, so that the cache can be relocated for a whole machine
+   without editing every project. An explicit :confval:`cache_policy` still wins over it.
+
+   .. versionadded:: 9.2
+
 .. envvar:: PYTEST_DEBUG
 
    When set, pytest will print tracing and debug information.
@@ -1246,6 +1265,14 @@ Environment variables that can be used to change pytest's behavior.
       Entry point names of installed plugins are now also accepted, in
       addition to importable module names.
 
+.. envvar:: PYTEST_HYPERLINKS
+
+   When set to ``1``, pytest emits OSC 8 terminal hyperlinks, so that paths it prints are clickable.
+   When set to ``0``, it never does. Otherwise they are emitted whenever terminal color is in use and
+   the terminal is not one known to mishandle them.
+
+   .. versionadded:: 9.2
+
 .. envvar:: PYTEST_THEME
 
    Sets a `pygment style <https://pygments.org/docs/styles/>`_ to use for the code output.
@@ -1373,14 +1400,38 @@ passed multiple times. The expected format is ``name=value``. For example::
 
 .. confval:: cache_dir
    :type: ``str``
-   :default: ``".pytest_cache"``
+   :default: ``""``
 
-   Sets the directory where the cache plugin's content is stored.
+   Sets the directory where the cache plugin's content is stored, overriding :confval:`cache_policy`.
    Directory may be relative or absolute path. If setting relative path, then directory is created
    relative to :ref:`rootdir <rootdir>`. Additionally, a path may contain environment
    variables, that will be expanded. For more information about cache plugin
    please refer to :ref:`cache_provider`.
 
+   When unset, the location is decided by :confval:`cache_policy` instead.
+
+   .. versionchanged:: 9.2
+
+      The default is now empty rather than ``".pytest_cache"``, so that leaving it unset can be told
+      apart from setting it. The resulting location is unchanged.
+
+.. confval:: cache_policy
+   :type: ``Literal["local", "user"]``
+   :default: ``"local"``
+
+   .. versionadded:: 9.2
+
+   Chooses where the cache directory lives, without spelling out a path:
+
+   * ``local`` - ``<rootdir>/.pytest_cache``.
+   * ``user`` - a per-project directory inside the platform's user cache directory. Requires the
+     ``xdg`` extra (``pip install pytest[xdg]``).
+
+   Ignored when :confval:`cache_dir` is set. The default can be set for a whole machine with the
+   :envvar:`PYTEST_CACHE_POLICY` environment variable.
+
+   See :ref:`cache_location` and :ref:`cache_pruning`.
+
 .. confval:: collect_imported_tests
    :type: ``bool``
    :default: ``true``
@@ -3245,6 +3296,21 @@ Cache
     Remove all cache contents at start of test run.
     See :ref:`cache`.
 
+.. option:: --cache-list
+
+    List the cache directories under the user-level cache root, don't perform collection or tests.
+    See :ref:`cache_pruning`.
+
+    .. versionadded:: 9.2
+
+.. option:: --cache-prune=SELECTOR
+
+    Remove cache directories or scopes under the user-level cache root, don't perform collection or
+    tests. ``SELECTOR`` is ``all``, ``orphaned``, ``stale``, or a glob matched against the directory
+    name and the origin path. May be given more than once. See :ref:`cache_pruning`.
+
+    .. versionadded:: 9.2
+
 Warnings
 ~~~~~~~~
 
@@ -3490,6 +3556,15 @@ All the command-line flags can also be obtained by running ``pytest --help``::
                             Show cache contents, don't perform collection or
                             tests. Optional argument: glob (default: '*').
       --cache-clear         Remove all cache contents at start of test run
+      --cache-list          List the cache directories under the user-level
+                            cache root, don't perform collection or tests.
+      --cache-prune=SELECTOR
+                            Remove cache directories or scopes under the user-
+                            level cache root, don't perform collection or tests.
+                            SELECTOR is 'all', 'orphaned', 'stale', or a glob
+                            matched against the directory name and the origin
+                            path. May be given more than once. See --cache-list
+                            first.
       --lfnf, --last-failed-no-failures={all,none}
                             With ``--lf``, determines whether to execute tests
                             when there are no previously (known) failures or
@@ -3755,7 +3830,12 @@ All the command-line flags can also be obtained by running ``pytest --help``::
                             Option flags for doctests
       doctest_encoding (string):
                             Encoding used for doctest files
-      cache_dir (string):   Cache directory path
+      cache_dir (string):   Cache directory path; overrides cache_policy
+      cache_policy ('local' | 'user'):
+                            Where the cache directory lives: 'local'
+                            (rootdir/.pytest_cache) or 'user' (the platform's
+                            user cache directory, keyed by project). Ignored if
+                            cache_dir is set.
       log_level (string):   Default value for --log-level
       log_format (string):  Default value for --log-format
       log_date_format (string):