December 2, 2016 2:00 pm

Symlinks in Windows 10!

By / Lead Senior Program Manager

Overview

Symlinks, or symbolic links, are “virtual” files or folders which reference a physical file or folder located elsewhere, and are an important feature built in to many operating systems, including Linux and Windows.

The Windows’ NTFS file system has supported symlinks since Windows Vista.  However, it hasn’t been easy for Windows developers to create symlinks.  In our efforts to continually improve the Windows Developer experience we’re fixing this!

Starting with Windows 10 Insiders build 14972, symlinks can be created without needing to elevate the console as administrator. This will allow developers, tools and projects, that previously struggled to work effectively on Windows due to symlink issues, to behave just as efficiently and reliably as they do on Linux or OSX.

Background

A symlink is essentially a pointer to a file or folder located elsewhere, consumes little space and is very fast to create (compared to copying a file and its contents).

Because of this, developers often replace duplicate copies of shared files/folders with symlinks referencing physical files/folders. Replacing redundant copies of files can save a great deal of physical disk space, and significantly reduce the time taken to copy/backup/deploy/clone projects.

In UNIX-compatible operating systems like Linux, FreeBSD, OSX, etc., symlinks can be created without restrictions.

However, for Windows users, due to Windows Vista’s security requirements, users needed local admin rights and, importantly, had to run mklink in a command-line console elevated as administrator to create/modify symlinks. This latter restriction resulted in symlinks being infrequently used by most Windows developers, and caused many modern cross-platform development tools to work less efficiently and reliably on Windows.

Now in Windows 10 Creators Update, a user (with admin rights) can first enable Developer Mode, and then any user on the machine can run the mklink command without elevating a command-line console.

What drove this change?

The availability and use of symlinks is a big deal to modern developers:

Many popular development tools like git and package managers like npm recognize and persist symlinks when creating repos or packages, respectively. When those repos or packages are then restored elsewhere, the symlinks are also restored, ensuring disk space (and the user’s time) isn’t wasted.

Git, for example, along with sites like GitHub, has become the main go-to-source code management tool used by most developers today.

picture1

Figure 1: SCM Tool Trends 2004-2016 (Source, Google)

The use of package managers in modern development has also exploded in recent years. For example, node package manager (npm) served ~400 million installs in the week of July 1st 2015, but served more than 1.2 billion installs just one year later – a 3x increase in just one year! In late June 2016, npm served more than 1.7 billion node packages in just seven days!

Figure 2: npm served 1.2Bn downloads in the first week of July 2016

Figure 2: npm served 1.2Bn downloads in the first week of July 2016

There are clear drivers demanding that Windows enables the ability to create symlinks to non-admin users:

  • Modern development projects are increasingly portable across operating systems
  • Modern development tools are symlink-aware, and many are optimized for symlinks
  • Windows developers should enjoy a development environment that is at least the equal of others

How to use Symlinks

Symlinks are created either using the mklink command or the CreateSymbolicLink API

mklink

  • There is no change in how to call mklink.  For users who have Developer Mode enabled, the mklink command will now successfully create a symlink if the user is not running as an administrator.

CreateSymbolicLink

  • To enable the new behavior when using the CreateSymbolicLink API, there is an additional dwFlags option you will need to set:
Value Meaning
SYMBOLIC_LINK_FLAG_ALLOW_UNPRIVILEGED_CREATE
0x2
Specify this flag to allow creation of symbolic links when the process is not elevated

Example Use

In the example below:

  • A subfolder folder called “animals” containing three files (cat.txt, dog.txt, and fish.txt)
  • (green) The mklink command is executed to create a symlink called “pet.txt” pointing at the “animals\dog.txt” file
  • (blue) When the contents of the current folder are listed, the symlink can be seen (yellow)
  • (purple) When contents of pet.txt are queried, the content of the referenced file (“dog.txt”) is displayed

picture3

Once created, symlinks can be opened, loaded, deleted, etc., just like any other file. Here, the pet.txt symlink is being opened in Notepad (red):

picture4

How do I try it?

This new symlinks support first shipped in Windows 10 Insiders Build 14972, and will be formally delivered in Windows 10 Creators Update. We are also working with the owners of open-source community tools such as Git and npm so they know symlink improvements are coming and can make the necessary changes to better support symlinks on Windows.

We encourage you to take this new feature for a spin and be sure to let us know via the Windows 10 Feedback hub or on Twitter etc. (see below). Please sign up for the Windows Insiders program if you haven’t already to try out symlinks!

Neal, Yosef (@yosefdurr), Rich (@richturn_ms), and Gilles (@khouzam).

Updated December 2, 2016 2:51 pm

Join the conversation

  1. That is a good start but I don’t understand the requirement of the dev mode. That is one more special case tool developers have to handle. Users can switch anytime from dev to normal mode (i can only imagine the headache when it happens in the middle of a git operation)… symlinks should just work, for anyone like on any other platform without requiring special privileges.

    • The ability to create symlinks previously required admin privileges because they introduce very real security risks.

      Since enabling developer mode requires local admin rights, and symlinks are of particular interest and value to developers, the rules around creating symlinks were relaxed a little to allow developers who (at least at some point) have admin rights.

  2. How about adding a powershell cmdlet built in?

    Especially with the switch from command prompt to powershell as default shell, not supporting symbolic links and junctions natively seems not good.

    • You can, in fact, create symlinks in PowerShell using:
      `New-Item -ItemType SymbolicLink -Name … -Target …`
      or by invoking mklink in cmd:
      `cmd /c “mklink “`

      HOWEVER, the New-Item method doesn’t yet understand the new symlink creation semantics and doesn’t yet support the new SYMBOLIC_LINK_FLAG_ALLOW_UNPRIVILEGED_CREATE flag. The PowerShell team do, however, have a bug tracking this fact and will no doubt fix it in due course:
      https://github.com/PowerShell/PowerShell/issues/2845

  3. There should be an mklink equivalent in Powershell (New-Symlink) without having to install PSCX

  4. This article is badly missing essential details, like,
    (1) Why the decision to require elevation for symlinks in the first place (while directory junctions would go unelevated)?
    (2) What has changed now (from security standpoint) that it’s become possible to lift that limitation?
    (3) As this isn’t enabled in the civil mode out of the box, what exactly is the security risk of enabling this in developer mode?
    (4) Same for the function flag, what is the security risk of passing it, supposing it hasn’t been introduced just to advertise the feature?

    • Hi Serge,

      1: There are some well documented security concerns with symlinks and that hasn’t changed
      2: Administrator rights are still required because an admin user is required to enable developer mode.
      3: Developer mode is provided as a means to enabling developer scenarios that can also require a change in security settings. In this case the additional risk if you enable this is now apps can create symlinks without being run elevated. That is why we’re currently limiting this ability to developers who are the ones who have asked for it. Low integrity apps are still blocked from creating symlinks.
      4: The flag exists to ensure the developer calling the API is opting in to leverage the new behavior. We can’t assume all existing apps want this behavior.

  5. This looks like the same problem shortcuts were designed to solve, albeit with hopefully better support. Are there plans to move away from shortcuts in the future?

    Why do we need admin privileges to create a link? The development mode trick is only useful to devs. If an app wants to use this feature then having users turn on dev mode would be difficult and a security hole since it also turns on other dev features. Why can this not be a standalone feature?

    What about ntfs permissions? Does deleting a symlink also delete the underlying file? Since most apps aren’t symlink aware, if I check to see if a user has permissions to the symlink file would I get the actual links securing or the symlink? Seems like this could cause issues since I may have delete rights to the symlink file but not the original file.

  6. Cool. Can you make it available in the Windows File Explorer? For example:

    1. Right-click file or folder that should by linked.
    2. Select context menu item “Copy”.
    3. Then, at the destination folder, there is a new context menu item “Paste as Symlink” that finally creates the link to the copied file or folder.

    You could also include it in the context menu of a Drop-operation when using Drag & Drop.

  7. I still can’t seem to get it to work on CIFS, even with the secret handshake.

    net use Z: \\somewhere\somedirectory
    Z:
    fsutil behavior set SymlinkEvaluation L2L:1 R2R:1 L2R:1 R2L:1
    echo hello > foo
    mklink bar foo
    –> Access is denied

  8. I create a Junction using mklink in build 15002, and I commit these file in git, then clone it into the other folder, and I find that the junction symlink becomes a directory
    Is it a bug or just I create the junction in a wrong way?

    • Junctions and Symlinks are different. Both are implemented under the covers as “reparse points” (special file system nodes that invoke a special behavior in a file system driver when opened/traversed) but junctions are much older (they’ve been part of NTFS since at least Windows 2000, maybe earlier) and work a bit differently (they always hold absolute paths, not relative ones, and I believe they cannot refer to remote files).

      Use the `/D` option in `mklink`, rather than `/J`, to create a directory symlink instead of a junction.