Use LOCALAPPDATA for config/cache directories on Windows by VedantMadane · Pull Request #30975 · matplotlib/matplotlib · GitHub

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

Windows app data storage: https://docs.microsoft.com/en-us/windows/apps/design/app-settings/store-and-retrieve-app-data
Discussion in issue about using proper Windows paths

Closes #20779

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

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.

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

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.

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

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

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.

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

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.

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

@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 if everything else is ok, can't we just squash-merge?

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

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

Changes were cleaned up.

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

PR: matplotlib#30975 Issue: matplotlib#20779 Base commit: b83305e Changed lines: 85

timhoffm reviewed Jan 16, 2026

View reviewed changes

Comment thread lib/matplotlib/tests/test_matplotlib.py Outdated

Comment thread lib/matplotlib/tests/test_matplotlib.py Outdated

timhoffm approved these changes Jan 16, 2026

View reviewed changes

timhoffm reviewed Jan 16, 2026

View reviewed changes

melissawm added OS: Microsoft PR: bugfix Pull requests that fix identified bugs labels Jan 21, 2026

scottshambaugh approved these changes Feb 9, 2026

View reviewed changes

scottshambaugh added the status: needs rebase label Feb 9, 2026

github-actions Bot removed the status: needs rebase label Feb 9, 2026

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

QuLogic previously requested changes Feb 11, 2026

View reviewed changes

Comment thread .github/workflows/tests.yml

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

tacaswell added this to the v3.11.0 milestone Mar 1, 2026

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

VedantMadane force-pushed the fix-windows-config-directory branch from ce421a8 to 6dd3a69 Compare March 2, 2026 12:29

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

tonybaloney pushed a commit to tonybaloney/swe-complex-matplotlib that referenced this pull request Mar 19, 2026

Human gold patch for matplotlib__matplotlib-30975

ee8d818

PR: matplotlib#30975 Issue: matplotlib#20779 Base commit: b83305e Changed lines: 85

+                  # Clear cached values
+                  matplotlib.get_configdir.cache_clear()
+                  matplotlib.get_cachedir.cache_clear()

Use LOCALAPPDATA for config/cache directories on Windows by VedantMadane · Pull Request #30975 · matplotlib/matplotlib · GitHub

Repository navigation

Use LOCALAPPDATA for config/cache directories on Windows - #30975

Use LOCALAPPDATA for config/cache directories on Windows#30975QuLogic merged 1 commit intomatplotlib:mainmatplotlib/matplotlib:mainfrom VedantMadane:fix-windows-config-directoryVedantMadane/matplotlib:fix-windows-config-directoryCopy head branch name to clipboard

Conversation

VedantMadane commented Jan 16, 2026

Summary

Changes

References

Uh oh!

timhoffm left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

VedantMadane commented Jan 16, 2026

Uh oh!

timhoffm Jan 16, 2026

Choose a reason for hiding this comment

Uh oh!

tacaswell commented Jan 16, 2026

Uh oh!

VedantMadane commented Jan 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

timhoffm commented Jan 19, 2026

Uh oh!

scottshambaugh commented Feb 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

scottshambaugh left a comment

Choose a reason for hiding this comment

Uh oh!

scottshambaugh commented Feb 9, 2026

Uh oh!

timhoffm commented Feb 10, 2026

Uh oh!

Uh oh!

tacaswell commented Mar 1, 2026

Uh oh!

timhoffm commented Mar 1, 2026

Uh oh!

tacaswell commented Mar 2, 2026

Uh oh!

VedantMadane commented Mar 2, 2026

Uh oh!

Uh oh!

QuLogic commented Mar 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

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

VedantMadane commented Jan 16, 2026 •
edited
Loading

scottshambaugh commented Feb 4, 2026 •
edited
Loading