When working with SharePoint Document Libraries, you often want users to download a file directly rather than opening it in a browser preview. Whether you are dealing with Excel workbooks, PDF documents, or specialized files like exported Web Parts (.dwp), the default browser behavior can be frustrating. Modern browsers often attempt to render these files internally, which might not be the workflow your users need.

In this guide, you will learn how to bypass the standard file-opening behavior and create a link that triggers the 'Download a Copy' action automatically. This is particularly useful when you lack administrative access to change site collection settings or farm-level file handling headers.

The Challenge of Browser File Previews

By default, SharePoint and modern browsers work together to provide a seamless preview experience. While this is great for quickly reading a document, it creates hurdles for developers who need to ensure a file is saved locally for editing or archival.

For example, if you link directly to a document URL, the browser typically checks the MIME type. If it recognizes the format (like a .pdf or .xlsx), it opens the file in a new tab. To force a download, you need to route the request through a specific SharePoint layout page designed to handle file streams: download.aspx.

Using the download.aspx Layout Page

The most reliable way to force a download is to use the download.aspx utility page located in the SharePoint _layouts folder. This page accepts a SourceUrl parameter, reads the content of the file, and renders it back to the user as an HTTP response with a 'Content-Disposition: attachment' header.

To construct this link manually, use the following format:

http://your-sharepoint-site/_layouts/15/download.aspx?SourceUrl=http://your-sharepoint-site/Documents/your-file.docx

Why This Works

By targeting download.aspx, you are telling SharePoint to treat the request as a file transfer rather than a navigation request. The server fetches the document at the SourceUrl and serves it directly to the browser's download manager. This method works across most versions of SharePoint, including SharePoint 2013, 2016, 2019, and SharePoint Online.

How to Find the Exact Download URL Using Browser Dev Tools

Sometimes, constructing the URL manually is difficult, especially if your site uses complex subsite structures or unique encoding. If you are having trouble building the correct string, you can use your browser's Developer Tools to capture the exact link SharePoint uses when you click the native 'Download a Copy' button.

  1. Navigate to your SharePoint Document Library.
  2. Press F12 to open Developer Tools.
  3. Switch to the Network tab.
  4. Click the Record or 'Start capturing' button if it isn't already active.
  5. Click the 'Download a Copy' button for the document in the SharePoint ribbon or context menu.
  6. Look for a request starting with download.aspx in the list of network activity.
  7. Right-click the request and select Copy URL.

This captured URL provides the perfect template for any hyperlinks you need to embed elsewhere on your site.

If you have a page with dozens of links that you want to convert into download links automatically, manual construction is inefficient. You can use a jQuery script to find specific file types (like .xlsx or .pdf) and dynamically rewrite their href attributes to use the download.aspx fix.

Below is a comprehensive script that handles relative paths and multiple subdomains. This script specifically targets Excel files, but you can modify the selector to include any file extension.

$(document).ready(function(){
    $('a[href$=" .xlsx"], a[href$=" .xls"]').each(function() {
        var excelURL = $(this).attr('href');
        var finalModifiedExcelURL;
        var testHTTP = 0;
        var testSub1 = 0;
        var testSub2 = 0;
        var testSub3 = 0;

        /* Default value for URL base */
        var siteDomain = "https://sub1.yourdomain.com";

        var pathToSite;
        var startOfPathToSite;
        var endOfPathToSite; 

        /* Testing if it's a relative URL vs. absolute URL */
        if (excelURL.indexOf("https://") === 0) {
            testHTTP = 1;
        }
        else if (excelURL.indexOf("http://") === 0) {
            testHTTP = 1;
        }
        else {
            /* This means it is a relative path */
            testHTTP = 2;   
        }

        /* Check which subdomain the file resides on */
        if (excelURL.indexOf("sub1.yourdomain.com") > 0) {
            testSub1 = 1;
            siteDomain = "https://sub1.yourdomain.com";
        }

        if (excelURL.indexOf("sub2.yourdomain.com") > 0) {
            testSub2 = 1;
            siteDomain = "https://sub2.yourdomain.com";
        }

        if (excelURL.indexOf("sub3.yourdomain.com") > 0) {
            testSub3 = 1;
            siteDomain = "https://sub3.yourdomain.com";
        }

        /* Modify links if they match our criteria */
        if (testSub1 === 1 || testSub2 === 1 || testSub3 === 1 || testHTTP === 2) {
            if (testHTTP === 1) {
                startOfPathToSite = excelURL.indexOf(".yourdomain.com") + 15;
            }
            else {
                startOfPathToSite = 0;
            }

            /* Find the point before the Documents library to slice the path */
            endOfPathToSite = excelURL.indexOf("/Documents/");
            pathToSite = excelURL.slice(startOfPathToSite, endOfPathToSite);

            /* Assemble the final URL */
            var downloadAspx = "/_layouts/15/download.aspx?SourceUrl=";
            var midDocPath = excelURL.slice(startOfPathToSite);
            var fieldURL = "&FldUrl=&Source=";
            var lastPart = siteDomain + pathToSite + "/Documents/Forms/AllItems.aspx";

            finalModifiedExcelURL = siteDomain + pathToSite + downloadAspx + midDocPath + fieldURL + lastPart;
        }

        /* Replaces the href value with the new direct download link */
        $(this).attr('href', finalModifiedExcelURL);
    });
});

How the Script Works

  1. Selector: The script looks for all anchor tags (<a>) where the href ends in .xlsx or .xls.
  2. Path Detection: It determines if the URL is absolute (starting with http) or relative.
  3. String Slicing: It identifies the subsite path and the library name (in this case, /Documents/).
  4. Reconstruction: It stitches together the siteDomain, the download.aspx layout path, and the original SourceUrl to create a valid download link.
  5. Injection: It updates the link's href attribute so that when a user clicks it, the download begins immediately.

Frequently Asked Questions

Does this work for users with Read-Only permissions?

Yes. As long as the user has permission to view the document, they can use the download.aspx method to download a copy. This method does not bypass SharePoint security; it simply changes how the browser handles the file delivery.

Can I use this for PDFs in SharePoint Online?

Absolutely. PDFs are the most common file type that browsers try to open internally. Using the SourceUrl parameter with download.aspx is the most effective way to force a PDF download in SharePoint Online without changing tenant-wide browser file handling settings.

What if my library isn't named 'Documents'?

If your library has a different name, you will need to update the string parsing logic in the JavaScript example (specifically the .indexOf("/Documents/") and lastPart variables) to match your library's internal name.

Wrapping Up

Creating a direct download link in SharePoint is a powerful way to improve user experience, especially for specialized file types or complex workflows. By utilizing the _layouts/download.aspx page, you can bypass browser defaults and ensure your users get the files they need exactly how they need them. Whether you construct these links manually for a few documents or use jQuery to automate the process across your entire site, this technique is an essential tool for any SharePoint developer's toolkit.