Move $PROFILE.CurrentUser* and friends out of documents #25097

Summary of the new feature / enhancement

With respect, apologies for the candor in this post.

Powershell's profile, modules, and configuration are all placed in directories that end up in documents because they scaffold off of HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Explorer\User Shell Folder\Personal.

Using the documents folder for configuration files and modules is absolutely ridiculous and against the conventions long established by shell configurations and tools. We do not place configuration in the user's documents folder. They are not documents. The user's profile and settings? Also not documents.

This poor default behavior is the source of many issues relating to modules. Issues PowerShell/PSResourceGet/issues/1494, #15552, and many, many others highlight just how problematic this default is.

Nothing that is stored here should be considered documents. The general user is not meant to see these. Worse, even, modern installs of Windows coerce users into having their home documents be stored on OneDrive.
As a result of the poor decision to build the $PROFILE.CurrentUser off of this variable, the user's profile, modules, and configuration files are all stored in the unintuitive personal documents folder, causing them to now sync to OneDrive by default.

Look at the number of upvotes for #15552 which has been enthusiastically requested—nay, demanded— by the community.
Please do not let this issue fall on deaf ears. And don't let the claims of "but this is a breaking change" deter anything. This is not a breaking change. Not when you give the option to migrate to the new location when installing the module.

This is an important issue. You have members of azure pleading for this behavior to change.
However, the issues that they are posting on are addressing the symptoms, not the cause. The cause is considering this registry key.

Now, in my opinion, the default location used to scaffold the rest should be ~/.powershell aka %USERPROFILE%\.powershell aka $env:USERPROFILE, though the convention in Windows would be somewhere in %APPDATA% ($env:APPDATA).

The best solution would be to have an environment variable (or a registry key?) that the user can change to set this path, and which defaults to one of the above when not set. Any other solution prevents users from easily placing this folder where they desire.

Sane defaults that follow well-established conventions are crucial. Please do not alienate your userbase. Almost all relevant developer programs place their configuration files either in %USERPROFILE% or %APPDATA%. Powershell must, too.

I already have a hard enough time convincing my colleagues that Powershell isn't a joke. I really like it, but they look at things like this and laugh it off.

Relevant discussions

From Rob Holt (@rjmholt): link

In terms of changing the default PSModulePath, there have been a lot of proposals to fix PSModulePath in various ways. Changing the CurrentUser path away from MyDocuments is going to break PowerShellGet, since it depends on the same location being used. However, the MyDocuments path clearly presents problems, and both the proposed alternatives ($env:LOCALAPPDATA\PowerShell\Modules and $HOME\PowerShell\Modules) make sense.

From Kirill Osenkov (@KirillOsenkov): link

... would it be possible to proritize this? I'm from Azure Data and we have very significant support costs in our org related to modules being in OneDrive.

From Keith Hill (@rkeithhill): link

My preference is ~\.pwsh (or ~\.powershell) on Windows. The Microsoft guidance is to use ~\AppData\Local\Microsoft\PowerShell or some folder like that under ~\AppData\Local. My problem with that is AppData is hidden which doesn't make for a great user experience when you tell folks to edit their ~\AppData\Local\Microsoft\PowerShell\profile.ps1 script. If they try to navigate to that file via File Explorer they're likely to get tripped up by the "missing" AppData dir.

From Olav Rønnestad Birkeland (@o-l-a-v) link

This is how PowerShell have worked since forever. We've requested the ability to choose path for years. I don't see it happening any time soon.

Sentiments like these indicate just how extremely infuriating this is.

And, posted almost four years ago, this gem from James Truher (@JamesWTruher) (link).

With behavior of OneDrive the WG agrees that we need to come up with a proper solution, however the scenarios have a high level of complexity which is exacerbated by the need that other PS tools also need to be able to use whatever solution is made available.

The WG proposes that PS should provide an API which allows tools to query for the default location of modules. The tool chain also needs to be able to query PS so the values are consistent.

We propose that an RFC is needed to define the behaviors, not only for PowerShell proper but for tools like PowerShellGet.

We think at least the following requirements need to be addressed in the RFC:

• where is the default location for PSModulePath (system and/or user)
• how may this default location be modified
• how is the API used by PS and the other tools
• how are misconfigurations handled (non-existing paths, multiple paths, etc)

What happened to that RFC? This was 4 years ago. What's going on?

This was shortly followed by this post by Ilya (@iSazonov)

I think it is good time to make the breaking change, preserve Document folder for module searching but install in new and more appropriate folder in user profile.

Proposed technical implementation details (optional)

No response