Skip to content

Use LOCALAPPDATA for config/cache directories on Windows#30975

Merged
QuLogic merged 1 commit intomatplotlib:mainfrom
VedantMadane:fix-windows-config-directory
Mar 2, 2026
Merged

Use LOCALAPPDATA for config/cache directories on Windows#30975
QuLogic merged 1 commit intomatplotlib:mainfrom
VedantMadane:fix-windows-config-directory

Conversation

@VedantMadane
Copy link
Contributor

Summary

On Windows, the default configuration and cache directories now use %LOCALAPPDATA%\matplotlib instead of %USERPROFILE%\.matplotlib, following Windows application data storage conventions.

This addresses the issue where matplotlib was placing its config folder directly in the user's home directory (%USERPROFILE%), which is not the recommended location on Windows.

Changes

  • Modified _get_config_or_cache_dir() to check for Windows (sys.platform == 'win32') and use %LOCALAPPDATA% when available
  • Falls back to %USERPROFILE%\.matplotlib if LOCALAPPDATA is not set
  • Updated docstrings for get_configdir() and get_cachedir() to document the Windows behavior
  • Added a test for the Windows-specific behavior
  • Added behavior change documentation

References

Closes #20779

Copy link
Member

@timhoffm timhoffm left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the contribution.

Please also check whether there are other parts of the documentation that may need an update: https://matplotlib.org/stable/search.html?q=MPLCONFIGDIR

@VedantMadane
Copy link
Contributor Author

Thanks for the review @timhoffm! I've addressed both suggestions: switched to pathlib for mkdir and added an explicit assertion for the expected configdir path.

Comment on lines +102 to +104
# Clear cached values
matplotlib.get_configdir.cache_clear()
matplotlib.get_cachedir.cache_clear()
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This does not work. But why do you need it? You run get_configdir() in a separate subprocess.

@tacaswell
Copy link
Member

What is the path for back compatibility?

We do not want to break users that have config they are relying on reading without warning and allow users to switch version of mpl without having to duplicate their config.

@VedantMadane
Copy link
Contributor Author

VedantMadane commented Jan 16, 2026

Thanks @timhoffm and @tacaswell for the feedback.

Changes made:
Removed unnecessary cache_clear() calls (subprocess starts fresh)
Added backwards compatibility:
Checks if %USERPROFILE%.matplotlib exists first
If exists, then use it (preserves existing user config)
If not, then use %LOCALAPPDATA%\matplotlib (new installs)
Updated test to set USERPROFILE to a temp dir to verify fresh install behavior

  • Existing Windows users: no change, their config stays where it is
  • New Windows users: get the proper %LOCALAPPDATA%\ location
  • Users can still override with \MPLCONFIGDIR\ if they want to migrate manually

@timhoffm
Copy link
Member

This compatibility looks reasonable to me. We can later decide whether we want to actively push towards the new location.

@melissawm melissawm added OS: Microsoft PR: bugfix Pull requests that fix identified bugs labels Jan 21, 2026
@scottshambaugh
Copy link
Contributor

scottshambaugh commented Feb 4, 2026

The fallback logic all looks correct to me, but could you please add a test for the case where %USERPROFILE%.matplotlib already exists? That wouldn't otherwise be exercised in CI, and I don't think too many of us on the dev team are on windows to verify that the migration is working.

Copy link
Contributor

@scottshambaugh scottshambaugh left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks like you need to rebase to main, but otherwise this looks good to me. Thanks for putting it together!

@scottshambaugh
Copy link
Contributor

Actually it looks like CI was unhappy for some other reason. Please rebase or re-push to kick off the tests again, and I'll merge after they pass.

@VedantMadane VedantMadane force-pushed the fix-windows-config-directory branch 2 times, most recently from e610dcc to 2a0795f Compare February 10, 2026 10:14
@timhoffm
Copy link
Member

There's a script issue in the step "Filter C coverage".

@VedantMadane VedantMadane force-pushed the fix-windows-config-directory branch from bc01142 to e1a4328 Compare February 28, 2026 14:53
@tacaswell
Copy link
Member

@VedantMadane Can you please squash this to one commit? I agree with @QuLogic there is a bunch of thrashing on tests.yml that is added and then removed.

@tacaswell tacaswell added this to the v3.11.0 milestone Mar 1, 2026
@timhoffm
Copy link
Member

timhoffm commented Mar 1, 2026

@tacaswell if everything else is ok, can't we just squash-merge?

@VedantMadane VedantMadane force-pushed the fix-windows-config-directory branch from e1a4328 to ce421a8 Compare March 1, 2026 10:58
@tacaswell
Copy link
Member

Technically yes. Either way I would like some clarity from @VedantMadane about what the (undone) changes were trying to do.

@VedantMadane
Copy link
Contributor Author

Technically yes. Either way I would like some clarity from @VedantMadane about what the (undone) changes were trying to do.

@tacaswell some test for other other operating system was failing. I worked on Windows specific functionality and was unsure how it could affect other OS' tests. I looked around other PRs to find if this was a problem with the test itself or something I did which was inadvertently affecting those. I was experimenting with things I could do to get the tests to pass. These were the changes that I later reverted.

On Windows, the default configuration and cache directories now use %LOCALAPPDATA%\matplotlib instead of %USERPROFILE%\.matplotlib, following Windows application data storage conventions. This PR adds backwards compatibility by checking if %USERPROFILE%\.matplotlib already exists before using the new location.

Closes matplotlib#20779
@VedantMadane VedantMadane force-pushed the fix-windows-config-directory branch from ce421a8 to 6dd3a69 Compare March 2, 2026 12:29
@QuLogic QuLogic dismissed their stale review March 2, 2026 15:38

Changes were cleaned up.

@QuLogic QuLogic merged commit 0984d6d into matplotlib:main Mar 2, 2026
40 checks passed
@QuLogic
Copy link
Member

QuLogic commented Mar 2, 2026

Thanks @VedantMadane! Congratulations on your first PR to Matplotlib 🎉 We hope to hear from you again.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

OS: Microsoft PR: bugfix Pull requests that fix identified bugs

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[ENH]: move .matplotlib folder from %USERPROFILE% on Windows

6 participants