Blog Post

Microsoft OneDrive Blog
4 MIN READ

Improved Filename and External Drive Support for OneDrive Mac

Jack_Nichols's avatar
Jack_Nichols
Icon for Microsoft rankMicrosoft
Jan 29, 2025

In early 2022, we launched a new Files- On-Demand experience for macOS, enhancing OS integration and support for new features like Known-Folder-Move (KFM). Since then, we’ve continued to refine this experience further, and today we’re excited to share two new features just for our Mac users! 

 

 

Syncing Special Characters 

OneDrive for Mac users can now create files that contain any of these special characters: 

"*:<>?/\| 

We know that this has been a pain point for our Mac user community, and we’re pleased to share that the latest version of OneDrive for Mac now supports them! Such files will sync to the cloud automatically, with no renames required by you.  New or existing files with these characters in the filename will automatically sync to the cloud after you receive the Sync App update of 24.206 or later. 

On a Mac, these characters will appear as you entered them in Finder as well as in other applications. Windows, iOS, Android, and web endpoints will show them in their HTML-encoded form (e.g. &#x2a; for “*”), so a file named “Hello * World.txt” on your Mac will show up as “Hello &#x2a; World.txt” on your PC. You can rename these files on another device too, and the special characters will be preserved on your Mac.  

 

 

Syncing to an External (Non-Home) Drive 

Previously, if you chose a path outside your home volume for OneDrive, your files would reside on your home volume, with the external drive serving as a cache. 

Now, when setting up OneDrive Sync in the first run experience, you can click ‘Change Location’ and select a non-home volume path, and it will place all your OneDrive content on that drive. Only a small amount of state is kept on your home volume, and this does not include your file data. With this experience, you can finally take full advantage of syncing to any drive you choose without using up space on your home volume! 

To take advantage of this new experience, there are a few requirements your Mac and external volume must meet: 

  • You must be running macOS 15.0 or later.  
  • You must be running OneDrive 25.004 or later. 
  • You must be in the Insiders ring. 
  • Your external volume must meet the following requirements: 
    • Non-removable/non-ejectable, as understood by macOS 
    • Formatted for APFS 
    • Protected by FileVault 
    • Not read-only, a network drive, or marked as quarantined by macOS 

Important: If you are already syncing OneDrive, you must first unlink and relink on the external drive to take advantage of this new experience.  

 

 

Filename FAQ 

  • Will any special character sync this way?  
    • No. Only the characters identified above will sync as-is. If you have other disallowed characters in filenames, you’ll need to rename them. Note that on a Mac, the “/” character shown in Finder is represented in the file system as “:”, so depending on where you view your file names you may see something different. 
  • What happens to filenames that already have an HTML-encoded character of this type in them? 
    • We’ll sync them to your Mac in their familiar name. That is, if you have a file named “Hello &#x3a; World.txt” already syncing, it will sync to your Mac as “Hello : World.txt”. Note that we will only apply a familiar name for the characters listed above. Arbitrary HTML-encoded characters will not be renamed. Decimal-encoded characters will not be renamed. 
  • What happens when I search for files containing one of these characters? 
    • Since the files on your Mac have these characters in them, you can search for them in Spotlight or similar as you would any other character. On the web, you can also search for these files as they appear on your Mac; the web will discard these characters but should return the correct result. On other endpoints, search behavior may vary. 
  • Why Mac only? 
    • We are exploring options on other platforms but wanted to prioritize our Mac customers first because these characters are allowed into the native filesystem, whereas on other platforms these characters are not allowed. 
  • Will this ever come to Windows? 
    • These special characters are illegal in filenames on Windows, so we don’t have plans to bring this to Windows at this time. On Windows, you’ll see them in their HTML-encoded forms in both the file system and in OneDrive’s activity center and other UI. 
  • Can an admin opt out of this experience for their users? 
    • Admins can opt-out of this feature by setting the “DisableNameMangling” default to YES. Remove this value to opt back in. 

 

External Drive FAQ 

  • What will the experience be on macOS versions older than 15.0? 
    • Users on these versions of macOS will get the previous experience, where the external drive is used as a cache and your files reside on the home volume. 
  • How can I know if I’m using the new experience? 
    • Your sync root will be on your external drive, not in ~/Library/CloudStorage. 
  • Are there behavior differences between the new and old experience? 
    • The new external drive sync experience works just like it does if you select your home drive.  
  • Why is FileVault a requirement? 
    • This is a system requirement of macOS. 
  • Are removable drives supported? 
    • OneDrive doesn’t support syncing to any drive that macOS thinks can be ejected.  

 

About Jack 

Jack Nichols is a Principal Software Architect on the OneDrive team and owns engineering for OneDrive for macOS. 

Updated Jan 30, 2025
Version 2.0
  • semvn's avatar
    semvn
    Brass Contributor

    Thanks, these are much needed updates.
    However, for now I'm out of luck ...

    • The latest version in the App Store, released yesterday (29/1) is 24.232.1118, not 25.004.
    • My files were on an external ssd, which was working fine, until yesterday I was forced to unlink the drive and re-install onedrive. Despite selecting the external drive for storage, the sync root seems to be in the home folder and internal disk space was used. As there was - obviously - insufficient disk space on my laptop, I could not sync all my files and had to remove some out of Onedrive.
    • Why not send a notification announcement before implementing such pervasive changes? We are working against tight deadlines and do not have four hours to spare to resynch and shuffle with files.
    • The concept of non-ejectable external disks escapes me.

    Folders concerned:

    /Users/MYNAME/Library/Group Containers/UBF8T346G9.OneDriveSyncClientSuite (82.6 GB)
    /Users/MYNAME/Library/CloudStorage/OneDrive-KULeuven (82.3 GB, probably a symlink to the first folder)
    As well as the external drive (98.14 GB - including some folders of colleagues I managed to synch before but probably can't sync now because it will eat up my internal disk space)

    • Jack_Nichols's avatar
      Jack_Nichols
      Icon for Microsoft rankMicrosoft

      Hi - thanks for your comments.

      The new external drive support is not yet available in the App Store. You must be on the Insiders ring which isn't available on the App Store version of OneDrive. We'll bring this to all of our users soon. 

      For users on an eligible build/the Insiders ring, we won't automatically switch to the new external drive experience. As mentioned in the blog, to opt-in, you need to unlink and relink your OneDrive to do so. We haven't decided yet whether we'll update automatically in the future, but for now you need to do it yourself if this is the experience you'd like.

      Some types of drives are considered removable by macOS, and can be ejected. OneDrive for Mac has never supported this type of drive, with or without the enhancments I've described here. The only change we're introducing is that the ~/Library/CloudStorage folder is now located on the drive you choose, instead of on your home volume.

      Thanks, Jack

      • heman64's avatar
        heman64
        Copper Contributor

        I am using OneDrive 25.005.0112.0003 ("Get OneDrive Insider Preview updates" is checked).

        I am also trying to move OneDrive data to an SSD.  I did as requested:

        • unlinked onedrive
        • created a new directory on the external SSD
        • relink OneDrive and chose the external SSD/OneDrive as a location.

        The surprising result is that OneDrive REPLACED my directory with a symlink back to the User CloudStorage directory.  It went from (using ls -l on terminal).

          64 Feb  4 21:13 OneDrive

        to:

        59 Feb  4 21:14 OneDrive -> /Volumes/USER/user1/Library/CloudStorage/OneDrive-Personal

        Is this version not the one in which it is supposed to work?

         

        Any help appreciated.