How to Fix Selenium PDF Automatic Download Not Working: Stop Firefox Download Dialog from Popping Up

Table of Contents#

1. Understanding the Problem: Why Firefox Shows the Download Dialog for PDFs
2. Prerequisites
3. Step-by-Step Guide to Configure Firefox for Automatic PDF Downloads
   • 3.1 Key Firefox Preferences to Disable the Dialog
   • 3.2 Implementing the Configuration in Selenium (Python Example)
4. Troubleshooting Common Issues
5. Conclusion
6. References

Understanding the Problem: Why Firefox Shows the Download Dialog for PDFs#

By default, Firefox handles PDFs in one of two ways:

• Preview in Browser: Using its built-in PDF viewer (pdf.js), which displays the PDF directly in the browser tab.
• Prompt for Action: If preview is disabled or the PDF is not supported, Firefox shows a pop-up dialog asking whether to "Open with" a default application (e.g., Adobe Acrobat) or "Save File" to the system.

For automation, neither behavior is ideal:

• Previewing the PDF means Selenium cannot interact with the download process.
• The pop-up dialog is a native OS window, and Selenium (a web automation tool) cannot control it, causing tests/scrapers to hang indefinitely.

The solution lies in configuring Firefox’s internal preferences to bypass the dialog and automatically save PDFs to a specified folder.

Prerequisites#

Before diving into the fix, ensure you have the following set up:

• Selenium WebDriver: Install via pip install selenium (Python) or your language’s package manager.
• Mozilla Firefox: Install the latest stable version (v90+ recommended for compatibility).
• GeckoDriver: The official driver for Firefox, required for Selenium to communicate with the browser. Download the version matching your Firefox install from the GeckoDriver Releases page, and add it to your system’s PATH.
• Basic Selenium Knowledge: Familiarity with initializing a WebDriver and running basic automation scripts.

Step-by-Step Guide to Configure Firefox for Automatic PDF Downloads#

The core of the solution is modifying Firefox’s about:config preferences via Selenium. These preferences tell Firefox to skip the dialog, disable PDF preview, and save files to a target folder.

3.1 Key Firefox Preferences to Disable the Dialog#

Firefox uses a set of internal preferences to control download behavior. Here are the critical ones for PDF auto-download:

3.2 Implementing the Configuration in Selenium (Python Example)#

Let’s translate these preferences into a working Selenium script. We’ll use Python for this example (the most popular language for Selenium), but the logic applies to other languages (Java, C#, etc.) with minor syntax adjustments.

Step 1: Import Required Libraries#

First, import Selenium’s webdriver and FirefoxOptions (to configure Firefox preferences). We’ll also use os to handle file paths.

from selenium import webdriver  
from selenium.webdriver.firefox.options import Options  
import os  

Step 2: Define the Download Directory#

Use an absolute path for the download folder to avoid permission issues. Create the folder if it doesn’t exist:

# Define the download directory (use absolute path)  
download_dir = os.path.abspath("selenium_pdfs")  # Saves to a folder named "selenium_pdfs" in the current working directory  
 
# Create the directory if it doesn't exist  
if not os.path.exists(download_dir):  
    os.makedirs(download_dir)  

Step 3: Configure Firefox Options with Preferences#

Initialize FirefoxOptions and add the key preferences from the table above:

# Initialize FirefoxOptions  
firefox_options = Options()  
 
# Set download preferences  
firefox_options.set_preference("browser.download.folderList", 2)  
firefox_options.set_preference("browser.download.dir", download_dir)  
firefox_options.set_preference("browser.download.useDownloadDir", True)  
 
# Auto-save PDFs (MIME type: application/pdf)  
firefox_options.set_preference("browser.helperApps.neverAsk.saveToDisk", "application/pdf")  
 
# Disable PDF preview (so Firefox doesn't open the PDF in the browser)  
firefox_options.set_preference("pdfjs.disabled", True)  
 
# Hide download manager window  
firefox_options.set_preference("browser.download.manager.showWhenStarting", False)  
firefox_options.set_preference("browser.download.manager.useWindow", False)  

Step 4: Initialize the Firefox Driver with Custom Options#

Pass the configured firefox_options to webdriver.Firefox() to launch Firefox with your settings:

# Initialize Firefox driver with the custom options  
driver = webdriver.Firefox(options=firefox_options)  
 
# Test the setup: Navigate to a page with a PDF download link  
driver.get("https://example.com/download-sample.pdf")  # Replace with your target PDF URL  
 
# Optional: Click the download link (if the PDF isn't auto-downloaded on page load)  
# driver.find_element(By.ID, "download-pdf-button").click()  
 
# Wait for the download to complete (adjust sleep time based on file size)  
import time  
time.sleep(10)  # Use WebDriverWait instead of sleep in production code  
 
# Close the driver  
driver.quit()  

Verification#

After running the script, check the selenium_pdfs folder (or your custom directory). The PDF should be saved there without any dialog prompts.

Java Example (Brief Overview)#

For Java users, the logic is similar. Here’s a snippet to set the preferences:

import org.openqa.selenium.WebDriver;  
import org.openqa.selenium.firefox.FirefoxDriver;  
import org.openqa.selenium.firefox.FirefoxOptions;  
 
public class FirefoxPDFDownload {  
    public static void main(String[] args) {  
        FirefoxOptions options = new FirefoxOptions();  
        options.addPreference("browser.download.folderList", 2);  
        options.addPreference("browser.download.dir", "/path/to/downloads");  
        options.addPreference("browser.download.useDownloadDir", true);  
        options.addPreference("browser.helperApps.neverAsk.saveToDisk", "application/pdf");  
        options.addPreference("pdfjs.disabled", true);  
 
        WebDriver driver = new FirefoxDriver(options);  
        driver.get("https://example.com/download-sample.pdf");  
        // ... rest of your code  
    }  
}  

Troubleshooting Common Issues#

Even with the above setup, you may encounter problems. Here are fixes for the most common scenarios:

Issue 1: The Download Dialog Still Pops Up#

• Root Cause: Incorrect MIME type. Some servers send PDFs with a generic MIME type like application/octet-stream instead of application/pdf.
• Fix: Check the PDF’s MIME type using your browser’s developer tools (Network tab > select the PDF request > Response Headers > Content-Type). Update browser.helperApps.neverAsk.saveToDisk to include the server’s MIME type (e.g., "application/pdf, application/octet-stream").

Issue 2: PDF Saves to Default Downloads Folder Instead of Custom Path#

• Root Cause: browser.download.dir uses a relative path or the folder lacks write permissions.
• Fix: Use an absolute path (e.g., "/home/user/selenium_pdfs" on Linux, "C:\\selenium_pdfs" on Windows) and ensure the folder exists with read/write permissions.

Issue 3: Firefox Still Previews the PDF in the Browser#

• Root Cause: pdfjs.disabled is not set to true, so the built-in PDF viewer is still active.
• Fix: Verify pdfjs.disabled is explicitly set to true in your options. Some Firefox versions may re-enable it by default.

Issue 4: GeckoDriver Throws Compatibility Errors#

• Root Cause: Mismatch between GeckoDriver, Firefox, and Selenium versions.
• Fix: Update to the latest versions:
  • Firefox
  • GeckoDriver
  • Selenium: pip install --upgrade selenium (Python) or update your Maven/Gradle dependency (Java).

Issue 5: Download Manager Window Still Appears#

• Root Cause: browser.download.manager.showWhenStarting or browser.download.manager.useWindow is not set to false.
• Fix: Ensure both preferences are added to your options.

Conclusion#

By configuring Firefox’s internal preferences via Selenium’s FirefoxOptions, you can eliminate the frustrating PDF download dialog and automate PDF saves seamlessly. The key steps are:

1. Setting a custom download directory.
2. Disabling the built-in PDF viewer.
3. Whitelisting the PDF MIME type to auto-save.

This approach works for PDFs and can be adapted to other file types (e.g., CSV, Excel) by updating the browser.helperApps.neverAsk.saveToDisk MIME type. Always test with your target website to ensure MIME types and download triggers align with your setup.

References#

• Selenium WebDriver Documentation
• Firefox Preferences Reference
• GeckoDriver Documentation
• MIME Types for Common File Formats
• Firefox PDF Viewer (pdf.js) Documentation