Fall back to hard link when symlink creation lacks privilege

[rich-purnell]

📖 Description

When WinGet runs without administrator privileges or Developer Mode enabled, std::filesystem::create_symlink() fails with the error:

Error code: 1314 - create_symlink: A required privilege is not held by the client.

This happens because creating symbolic links requires the SeCreateSymbolicLinkPrivilege, which is only granted to administrators or available when Developer Mode is turned on. While WinGet typically runs with those privileges, there are scenarios where they are not held — for example, when running as a standard user or in a restricted environment.

I wrote a local test program that confirmed this behavior. Under those conditions, std::filesystem::create_symlink(target, link) fails with the above error, but std::filesystem::create_hard_link(target, link) succeeds. Since a hard link provides identical file resolution behavior for this use case (pointing to the same file on disk), it is a viable fallback.

This change adds a fallback: when symlink creation fails specifically with ERROR_PRIVILEGE_NOT_HELD, the code attempts a hard link instead before returning false.

Such a change may not solve all problems (for example, in some special file system structures), but it can reduce the impact scope.

🔗 References

Resolves #6058

🔍 Validation

Build succeeds with no errors or warnings.

✅ Checklist

• Signed the Contributor License Agreement
• Linked to an issue
• Updated Release Notes (if applicable)
• Updated documentation (if applicable)
• Updated Copilot instructions (if build, architecture, or conventions changed)

📋 Issue Type

• Bug fix
• Feature
• Task

Microsoft Reviewers: Open in CodeFlow

[rich-purnell]

@microsoft-github-policy-service agree

[Trenly]

The uninstall flow may need to account for hard links with this change. Tests should be added to validate hardlink creation, path resolution, and removal.

What happens in the upgrade scenario where a hardlink exists but the user now has symlink permissions - does it stay a hardlink, or should it be replaced with a symlink?

[rich-purnell]

The uninstall flow may need to account for hard links with this change. Tests should be added to validate hardlink creation, path resolution, and removal.

What happens in the upgrade scenario where a hardlink exists but the user now has symlink permissions - does it stay a hardlink, or should it be replaced with a symlink?

I see that in the current installation flow, before creating a symlink, std::filesystem::remove(filePath) is called to remove the existing symlink. My testing shows that it also correctly removes hard links. So when a user gains permissions, reinstallation will remove the hard link and then create a symlink. I did overlook the uninstall part – I will check it later. Regarding adding new tests, since this is my first time working on this project, I need some time to understand which scenarios are already covered by the existing tests.

[Kobi-Blade]

Hard links only work when the link and target are on the same NTFS volume, and they cannot link directories at all.

WinGet needs cross volume and directory level linking for portable packages, and it must track and remove links cleanly during upgrades.

Symlinks support all of that, hard links don’t.

[sysopmd]

Hard links only work when the link and target are on the same NTFS volume, and they cannot link directories at all.

WinGet needs cross volume and directory level linking for portable packages, and it must track and remove links cleanly during upgrades.

Symlinks support all of that, hard links don’t.

I was about to post a similar comment. However, I expect that a winget user is a more-than-average expert user, so they just need the proper guidance. I think the following should work:

• if symlink works, just use that
• if not, try and fallback on hard link, possibly advising the user with a warning, explaining that winget works best in developer mode, where it can use symlinks, and now we are using a hardlink fallback
• if hard link creation fails, fail the installation or at least show an error, explain to the user the reason and advice to either use developer more or high privileges. One could also suggest to retry installation with elevated privileges as follows winget install <package-id> --scope user. Did I get it right that this should install as user without the permission problem? Of course it is not viable if the user does not have admin access, but at least the user knows her/his options

[Kobi-Blade]

Hard links only work when the link and target are on the same NTFS volume, and they cannot link directories at all.
WinGet needs cross volume and directory level linking for portable packages, and it must track and remove links cleanly during upgrades.
Symlinks support all of that, hard links don’t.

I was about to post a similar comment. However, I expect that a winget user is a more-than-average expert user, so they just need the proper guidance. I think the following should work:

• if symlink works, just use that
• if not, try and fallback on hard link, possibly advising the user with a warning, explaining that winget works best in developer mode, where it can use symlinks, and now we are using a hardlink fallback
• if hard link creation fails, fail the installation or at least show an error, explain to the user the reason and advice to either use developer more or high privileges. One could also suggest to retry installation with elevated privileges as follows winget install <package-id> --scope user. Did I get it right that this should install as user without the permission problem? Of course it is not viable if the user does not have admin access, but at least the user knows her/his options

On that note, this PR was created because the average WinGet user is often not aware they should be running in developer mode or with elevation.

This PR is more prone to generating issue reports, and doesn't solve the root problem.

Honestly, we should be solving the symlink problem directly with more robust error checking and handling. For instance, we can trigger an elevated command for the symlink (which will prompt UAC), if the initial link creation fails due to permissions issues.

[sysopmd]

ok, sorry, I thought that UAC was not a possibility for some reason. Then I understand it is preferrable to my suggestion about elevated '--scope' command.
However my understanding is that winget is designed to work for regular, non-elevated users without any special developer settings enabled.
So in this case, I think the original PR was a way to ease the user experience. However, we can also state that if a package require symlinks, then elevation or developer mode is required. I wonder which is the best way to communicate to the user that what they are seeing depends on the characteristic of the package they are installing and why.
Likely, elevation with UAC prompt provides a smoother experience. However, the user should be informed that they can also opt for developer mode.

Hard links only work when the link and target are on the same NTFS volume, and they cannot link directories at all.
WinGet needs cross volume and directory level linking for portable packages, and it must track and remove links cleanly during upgrades.
Symlinks support all of that, hard links don’t.

I was about to post a similar comment. However, I expect that a winget user is a more-than-average expert user, so they just need the proper guidance. I think the following should work:

• if symlink works, just use that
• if not, try and fallback on hard link, possibly advising the user with a warning, explaining that winget works best in developer mode, where it can use symlinks, and now we are using a hardlink fallback
• if hard link creation fails, fail the installation or at least show an error, explain to the user the reason and advice to either use developer more or high privileges. One could also suggest to retry installation with elevated privileges as follows winget install <package-id> --scope user. Did I get it right that this should install as user without the permission problem? Of course it is not viable if the user does not have admin access, but at least the user knows her/his options

On that note, this PR was created because the average WinGet user is often not aware they should be running in developer mode or with elevation.

This PR is more prone to generating issue reports, and doesn't solve the root problem.

Honestly, we should be solving the symlink problem directly with more robust error checking and handling. For instance, we can trigger an elevated command for the symlink (which will prompt UAC), if the initial link creation fails due to permissions issues.

[Kobi-Blade]

ok, sorry, I thought that UAC was not a possibility for some reason. Then I understand it is preferrable to my suggestion about elevated '--scope' command. However my understanding is that winget is designed to work for regular, non-elevated users without any special developer settings enabled. So in this case, I think the original PR was a way to ease the user experience. However, we can also state that if a package require symlinks, then elevation or developer mode is required. I wonder which is the best way to communicate to the user that what they are seeing depends on the characteristic of the package they are installing and why. Likely, elevation with UAC prompt provides a smoother experience. However, the user should be informed that they can also opt for developer mode.

Keep in mind that the elevated command would only create the symlink, the package would still be installed in the user scope.

WinGet already informs the user that it lacks permissions in its current implementation, https://github.com/microsoft/winget-cli/blob/master/src/AppInstallerSharedLib/Filesystem.cpp#L466

I do not disagree with anything you've said. I just don't believe this PR is the solution we should be looking for, and I mean no offense to the original poster.

[sysopmd]

I see. I am not familiar with winget development. I hope I am not creating useless noise, please tell me if this is the case.
My intent here is to provide user-level feedback.

Regarding your last comment

WinGet already informs the user that it lacks permissions in its current implementation, https://github.com/microsoft/winget-cli/blob/master/src/AppInstallerSharedLib/Filesystem.cpp#L466

I did not have such experience (see my comment on 6058): no user-visible feedback was provided in case the symlink fails.
But then the tools does not work. In PortableInstaller.cpp I see that messages are logged, but they do not reach the user (at least they did not in my attempt - should I try a more recent version?). The path addition does not always help because sometimes link names are different than exe name.

Summarizing I think that requesting elevation is a good fix, but I would add a message explaining why elevation is required.
And in case the user cancels and the link cannot be created, I think there should be proper messaging indicating an installation failure or at least that the package might misbehave. Does it make any sense?

[rich-purnell]

1. Thank you for your attention on this matter.

2. As a user, after installing Godot using winget install -e --id GodotEngine.GodotEngine, I received the following output:

Added command line alias: "godot"
Added command line alias: "godot_console"
Successfully installed
Note: Note when running WinGet to Install This Package *Without Admin Privileges*:
WinGet *Can Not* Create Command Line Alias(es) unless Admin Privileges are provided, as without Admin Privileges Winget *Can Not* Create Symbolic Links for those Command Lines Aliases.

As you can see, it reports both success and failure. Prior to this installation, I had always assumed that the aliases were successfully created, because your "if alias creation fails, add the app's installation directory to PATH" strategy effectively deceived me into thinking that. It was only when I noticed that Godot's program names did not match the aliases that I began to investigate the issue. At that point, I discovered that "symlink creation" had never worked on my system.

3. When I understood the root cause, my first thought was "why not pop up a UAC elevation prompt?" However, after some consideration, I realized the reason. Windows inherently treats symlink creation as a potentially dangerous operation, and since WinGet's portable package manifests are community-contributed, arbitrarily providing administrator privileges would carry significant security risks.

4. Without privilege elevation, the only viable option for implementing aliases is hard links. As I noted in my PR description, hard links do not solve all problems, but they reduce the impact surface. Hard links are not suitable in two scenarios: a. %LOCALAPPDATA%\Microsoft\WinGet\Links and %LOCALAPPDATA%\Microsoft\WinGet\Packages reside on different NTFS volumes; b. an alias is needed for a directory. I have not encountered any use cases that require these scenarios. I understand that the installation location can be configured via options, but it would also be possible to create the corresponding Links directory on the relevant volume and add multiple Links directories to PATH. I would even argue that WinGet should completely replace symlinks with hard links, as they are more secure.

5. The worst-case outcome of attempting to fall back to a hard link when symlink creation fails is that nothing changes compared to the current strategy. However, if it succeeds, it resolves part of the alias creation failure problem.

6. The current PR is crude and unacceptable; for now, just treat it as a proof of concept. I am working on refining the code.

7. Until I saw that UAC is considered acceptable. Can you confirm this? Because that would render much of the discussion around this issue moot.

[Trenly]

Until I saw that UAC is considered acceptable. Can you confirm this? Because that would render much of the discussion around this issue moot.

One core tenet of WinGet is that it must be able to install applications unattended - if there were to be a UAC prompt, it should come right at the beginning while a user is still at the machine; However, with installer selection being potentially deferred, especially in the case of winget import I don’t know that it would be possible to make the determination of if elevation will be needed until too late in the install process

[florelis]

What are all the limitations with hard links? Just being on the same NTFS volume?
We could detect those conditions or the failure to create the hard link and just continue with the current behavior in that case.

So:
Dev mode or Admin -> Symlink
On same NTFS volume -> Hardlink
Not dev, not admin, on different NTFS volume -> Add install location to path

I think the last case would be extremely rare. The default locations for the executables and the links are both in %LocalAppData%\Microsoft\WinGet\. I don't see much reason for why someone would put that in a separate volumen.
If installing machine-wide to %ProgramFiles%\, then they have admin permissions and can make symlinks.
For hardlinks to not work, the user would need to have a custom install directory that lives in a separate volume. I don't think that would happen much for non devs.

[JohnMcPMS]

Symlinks have an additional property; the actual executable is located in its directory that may contain dependencies like DLLs. So to the running code, it appears to be at its resolved location, not the symlink. A hardlink would appear to be running at the hardlink location (it is just another "normal" file that happens to have the same data stream as another file).

One potential option for the issue of creating aliases would be to still add the location to PATH while creating the hardlinks in the target location (rather than the Links directory).

[sredna]

Symlinks have an additional property; the actual executable is located in its directory that may contain dependencies like DLLs.

This abstraction is not perfect, there are still cases where being a symlink is not the same as the real .exe.

This issue just further proves that using small forwarder/shim exe files is the best solution to solve the %path% question (IMHO).

[JohnMcPMS]

This issue just further proves that using small forwarder/shim exe files is the best solution to solve the %path% question (IMHO).

Those are problematic from a signing perspective, not to mention all of the ways in which perfectly forwarding everything from one process to another is difficult/fragile.

We should investigate the breadth of support for App Paths amongst users who are having issues with the current setup flow. If they are mostly using shells that integrate with this registration mechanism, it would probably be a better solution than continuing down the current path.

Overall, it would probably be good to have many of these options (and CLI params), choose the best defaults, and allow for winget repair to target portables while updating the mechanism by which they are linked into discovery.

[sredna]

Those are problematic from a signing perspective

If you don't care about the icon, it would just be the same WinGet provided shim that is signed (and hardlinked for each new app).

not to mention all of the ways in which perfectly forwarding everything from one process to another is difficult/fragile.

The only thing you have to forward is the command line arguments, everything else (environment and current directory) is automatic.

[florelis]

If you don't care about the icon, it would just be the same WinGet provided shim that is signed (and hardlinked for each new app).

That's problematic at least for cases where you want to run as admin.

If there is an UAC it should be "do you want to run Cool App, published by Contoso (verified by signature)?"

If we create a shim that is specific to this app, we could not sign it, so the UAC would be "do you want to run Cool App, published by Contoso (unverified)?" Not having the publisher verified should be a red flag for people running this.

If we use a common shim that we sign beforehand, the UAC would always say "do you want to run WinGet Shim, published by Microsoft (verified by signature)?" This could mislead people into thinking the app is trustworthy and from MS, not just a random app from who-knows-who.

[sredna]

That's problematic at least for cases where you want to run as admin.

The shim would never request UAC elevation in its manifest. If someone enumerates %path% searching for a specific filename and then on purpose uses "runas" with ShellExecute to elevate then yes, you would get a elevation request on the shim itself. But yes, this is a case that is problematic.