Chrome headless mode prevents file downloads from working

Other Questions Headless Browser
1

I’m having trouble with file downloads when running Chrome in headless mode

When I run my selenium tests with headless Chrome, files don’t get saved to my specified download folder. The weird thing is that everything works perfectly when I remove the headless argument. The download button clicks fine but no files appear in the target directory.

Here’s my current browser setup:

DesiredCapabilities capabilities = DesiredCapabilities.chrome();

HashMap<String, Object> preferences = new HashMap<String, Object>();
preferences.put("profile.default_content_setting_values.notifications", 2);
preferences.put("profile.default_content_settings.popups", 0);
preferences.put("download.default_directory", System.getProperty("user.dir") + File.separator + "downloads");

ChromeOptions options = new ChromeOptions();
options.addArguments("--headless", "window-size=1280,720", "--no-sandbox");   
options.addArguments("--disable-dev-shm-usage"); 
options.setExperimentalOption("prefs", preferences);
options.addArguments("disable-popup-blocking");
options.addArguments("--disable-extensions");
capabilities.setCapability(ChromeOptions.CAPABILITY, options);

Any ideas why headless mode breaks the download functionality?

2

Hit this same issue. Chrome headless won’t download without explicitly setting the behavior. Add --disable-features=VizDisplayCompositor to your options and use driver.execute_cdp_cmd('Page.setDownloadBehavior', {'behavior': 'allow', 'downloadPath': your_path}). Way more reliable than messing with prefs for headless downloads.

3

Headless Chrome blocks downloads by default - it treats headless mode as unsafe and cuts off file system access. Hit this same problem last year during automated testing. You’ll need to force downloads on by adding --disable-web-security and --allow-running-insecure-content to your ChromeOptions. Quick tip: use forward slashes in your download path even on Windows - headless Chrome’s finicky about path formatting. What worked better for me was intercepting download requests through Chrome DevTools Protocol instead of the normal download flow. Gives you way more control over file saving in headless mode.

4

Chrome DevTools Protocol is your best bet. Regular preferences get ignored in headless mode since Chrome treats it like a sandbox. I fixed this by enabling downloads through CDP commands before hitting the page. Use ((ChromeDriver) driver).executeCdpCommand("Browser.setDownloadBehavior", Map.of("behavior", "allow", "downloadPath", downloadPath)) right after you initialize the driver. Make sure your download directory exists first - headless Chrome won’t create it like regular mode does. Timing’s important too - run the CDP command before any navigation or it won’t stick.