Covenant Eyes Developer Portal

UNC Paths with Python

The Need: UNC Handling for Python on Windows

If you have ever needed to work with UNC paths in a Python script for Windows, you might have experienced the same dilemma that we did. What’s the problem? Python has virtually no support for UNC. According to its documentation, Python only recognizes the existence of UNC in two functions: os.path.ismount and os.path.split_unc . Even worse, a thorough search for a third-party library to deal with UNC paths turns up nothing. While none if this is terribly surprising (since Python’s natural habitat is definitely not Windows), it’s still frustrating for the tiny minority like us.

As long as the UNC path you’re dealing with doesn’t need anything complicated, it can be treated just like a local path. The problem arises when you need to authorize a connection before your UNC path can be accessed or when you want to mount it to a local drive letter. Further difficulty appears when you want to query the system for the UNC paths that are already connected or if you only want to mount a path if it isn’t already there.

As tiny as our minority might be, we wanted to deal with these difficulties once and for all. I introduce to you the win_unc library.

The Solution: win_unc Library

The gory details of installation and documentation are provided on win_unc’s GitHub page, but the most important aspects are summarized here.


win_unc is available from PyPI, so it can be installed like this:

However, installing via pip on Windows is not as trivial as it is on Linux. If you’re not familiar with that process, check out the documentation’s section on installation.

Basic Usage

The library breaks up UNC handling into three major classes:

  • UncDirectory for describing a UNC directory.
  • UncCredentials for describing a username and password that might be needed to connect to a particular UNC path.
  • UncDirectoryConnection for describing how the UNC path is seen by the Windows system.

The following example demonstrates how to describe your UNC path, any necessary credentials, and connect to it.

Once a UNC path is connected, it can be accessed like any local path.

Alternatively, you might want to mount the UNC path to a local drive letter. The following example demonstrates that:

In full disclosure, the UncDirectoryMount class mostly just provides aliases to UncDirectoryConnection‘s methods to be more semantic. You can achieve the exact same functionality with UncDirectoryConnection. One meaningful difference, however, is that when UncDirectoryMount is not provided a DiskDrive as a mount point, it will pick an available one and mount the UNC path anyway (as opposed to the UncDirectoryConnection class, which does not mount the UNC path without having a DiskDrive explicitly provided).

The following code will mount the UNC path to some available drive letter:

And that’s basically all there is to it!

Next Steps

If you see a feature to add, submit pull requests to the GitHub repo or report issues. The full documentation is at

Leave a reply