From 38693097f1bfcb8415ab623bd28c656cb6913762 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bern=C3=A1t=20G=C3=A1bor?= Date: Fri, 13 Feb 2026 13:50:37 -0800 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20docs(windows):=20document=20Stor?= =?UTF-8?q?e=20Python=20sandbox=20path=20behavior?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Windows Store Python (MSIX) uses kernel-level filesystem virtualization that redirects AppData writes to a per-package sandbox location. This causes confusion when paths returned by platformdirs are passed to external processes that run outside the sandbox. The returned logical paths are correct for the calling process, so this is not something platformdirs should resolve. Added a note explaining the behavior and the os.path.realpath() workaround for cross-process path sharing. Closes #90 --- docs/platforms.rst | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/docs/platforms.rst b/docs/platforms.rst index 046e01a..2ce448e 100644 --- a/docs/platforms.rst +++ b/docs/platforms.rst @@ -283,6 +283,33 @@ Key behaviors: which syncs across machines in a Windows domain - **OPINION**: ``user_cache_dir`` appends ``\Cache``, ``user_log_dir`` appends ``\Logs`` +.. note:: **Windows Store Python (MSIX)** + + Python installed from the Microsoft Store runs in a sandboxed (AppContainer) environment. + Windows silently redirects writes under ``AppData`` to a per-package private location, e.g. + ``AppData\Local\Packages\PythonSoftwareFoundation.Python.3.X_\LocalCache\Local\...``. + + ``platformdirs`` returns the logical ``AppData`` path, which is correct for code running inside + the same sandbox. However, if you pass these paths to external processes (subprocesses, other + applications), those processes may not see files created at the logical path because they run + outside the sandbox. + + To obtain the real on-disk path for sharing with external processes, call + :func:`os.path.realpath` on the path **after** the file or directory has been created: + + .. code-block:: python + + import os + import platformdirs + + data_dir = platformdirs.user_data_dir(appname="MyApp", appauthor="Acme", ensure_exists=True) + real_dir = os.path.realpath(data_dir) + + This is a Windows design limitation, not a ``platformdirs`` bug. See `Microsoft's MSIX + documentation + `_ + for details on filesystem virtualization. + .. autoclass:: platformdirs.windows.Windows :members: :show-inheritance: