Repository navigation
🐛 fix(app-data): build the default folder only when none is given - #3488
Merged
gaborbernat merged 4 commits intoOct 28, 2026
Merged
Conversation
load_app_data passed make_app_data(None, ...) as the default of --app-data, so the default folder was built while the option was being registered, before the command line, VIRTUALENV_APP_DATA or the ini file had been read. With --read-only-app-data that builds a ReadOnlyAppData for the default folder, which raises when the folder does not exist. Pointing a read-only run at a prebuilt cache with --app-data or VIRTUALENV_APP_DATA therefore failed on any machine without the default cache, such as a container user whose HOME does not exist or a fresh CI account, and the error named a folder the user never asked for. Writable runs created the unused default folder instead, and left a temporary folder behind when the default could not be used. Because the default was an AppData object, values from the environment or the ini file were also converted with the default's class rather than the option's type. VIRTUALENV_APP_DATA was dropped with a warning when the default had fallen back to temporary app-data, and in read-only mode a missing folder there fell back to the default instead of failing like --app-data does. The option now defaults to None and the default folder is built after parsing, only when no folder was given. The result is also stored on the action so --help still shows it when no folder was given. Environment and ini values now go through make_app_data the same way a command line value does.
for more information, see https://pre-commit.ci
Three tests repeated the same source parametrization and branched on it in a helper; a parametrized fixture now hands each test a function that gives the folder on the command line, in the environment or in the config file. The blocked default is set up by a parameter instead of an if, the help test annotates capsys, and each test asserts once.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
On a machine where the default app-data folder does not exist, a read-only run pointed at a prebuilt cache failed, and the error named the default folder instead of the one that was passed in. 🐛
HOME=/nonexistent virtualenv --read-only-app-data --app-data ./cache venvraisedread-only app data directory /nonexistent/.cache/virtualenv does not exist, andVIRTUALENV_APP_DATAfailed the same way. A missing default is common: a container running asnobody, a fresh CI account, or anXDG_CACHE_HOMEthat points nowhere. After this change a run uses the folder it was given and does not touch the default at all.virtualenv built the default app data while registering the
--app-dataoption, before the command line, environment orvirtualenv.iniwere read. In read-only mode that build failed on a missing default. In writable mode it created the default folder even when another one was named, and when the default could not be written it left an unclosed temporary folder behind. Because the default was already an app-data object, values fromVIRTUALENV_APP_DATAor the ini file were converted with its class instead of the option's own conversion, so a missing read-only folder in the environment silently fell back to the default. The option now has no default while parsing, and virtualenv builds the default folder afterwards, only when nothing was given. #3410 already rejected a bad command line before any app-data folder was created; this moves the default itself.VIRTUALENV_APP_DATAand ini values now get the same checks as--app-data, so a missing folder given that way fails in read-only mode instead of falling back.--helpstill prints the default folder, except together with--app-data, where it showsNonebecause the default is never built.Thanks for contributing, make sure you address all the checklists (for details on how see development documentation)
ran the linter to address style issues (
ruff checkandruff format; the other pre-commit hooks run in CI)wrote descriptive pull request text
ensured there are test(s) validating the fix
added news fragment in
docs/changelogfolderupdated/extended the documentation (no docs describe the old behavior; the generated CLI reference already calls the default the platform specific application data folder)
for changes to activation scripts,
pyvenv.cfg, wheel downloads, app-data or release workflows: the outside input is the app-data path from--app-data,VIRTUALENV_APP_DATAor the ini file. It is only ever used as a folder path, never run as code, and the change only decides whether the default folder gets built at all, so it removes a write rather than adding one.ran tests on Python 3.9 and 3.15 (ran on 3.14 on Windows and 3.12 on Linux directly with pytest; leaving 3.9 and 3.15 to CI)
linked upstream issues beside any temporary interpreter overrides (none)
kept the PR in draft until CI passes