Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Python Selenium: File Upload, Download, and Screenshots

Learn how to automate file uploads, manage downloads, and capture screenshots with Python Selenium WebDriver.

~5 min readPython
#selenium#python#web automation#file upload
Illustration of a Selenium WebDriver automating file upload, download, and screenshot capture in a browser.

Automating file interactions is a common requirement when building end-to-end tests with Python and Selenium WebDriver. Selenium provides direct methods for uploading files, but downloads and screenshots require careful configuration and waiting logic to behave reliably across browsers and environments.

Uploading Files with Selenium's send_keys

File uploads in Selenium are handled through the send_keys method on an <input type="file"> element. Unlike manual interaction, Selenium does not need to open the native file picker dialog. Instead, you directly set the file path on the input element.

python
from selenium import webdriver from selenium.webdriver.common.by import By driver = webdriver.Chrome() driver.get("https://example.com/upload") file_input = driver.find_element(By.CSS_SELECTOR, "input[type='file']") file_input.send_keys("/path/to/your/file.pdf") # Submit the form or trigger the upload via JavaScript if needed driver.find_element(By.ID, "submit").click()

For an input that supports multiple files, pass a newline-separated string of file paths:

python
file_input.send_keys("/path/to/file1.txt\n/path/to/file2.txt")

If your paths are in a list, build that string with "\n".join(paths).

The key constraint is that the element must be an <input> with type="file". If the upload widget is a custom JavaScript component that hides the native input, you may need to interact with the hidden input directly. In that case, ensure the element is present in the DOM, even if it is not visible. Selenium's send_keys works on hidden inputs as long as they are not disabled.

Configuring the Browser for Automatic Downloads

Unlike uploads, downloads are not handled by a single Selenium method. You must configure the browser to save files to a known directory without prompting, and then monitor that directory for the file to appear.

For Chrome, use add_experimental_option to set download preferences:

python
from selenium import webdriver options = webdriver.ChromeOptions() prefs = { "download.default_directory": "/path/to/downloads", "download.prompt_for_download": False, "download.directory_upgrade": True, "safebrowsing.enabled": True } options.add_experimental_option("prefs", prefs) driver = webdriver.Chrome(options=options)

For Firefox, use set_preference:

python
from selenium import webdriver options = webdriver.FirefoxOptions() options.set_preference("browser.download.folderList", 2) options.set_preference("browser.download.dir", "/path/to/downloads") options.set_preference("browser.download.useDownloadDir", True) options.set_preference("browser.helperApps.neverAsk.saveToDisk", "application/pdf,text/plain") options.set_preference("pdfjs.disabled", True) # for PDFs driver = webdriver.Firefox(options=options)

These preferences tell the browser to automatically save files to a specific folder and suppress the download prompt. The MIME types in neverAsk.saveToDisk should match the files you expect to download. You may need to adjust them based on your test data.

Waiting for Downloads to Complete

After triggering a download, you cannot assume the file exists immediately. The browser downloads asynchronously, and you need to wait until the file is fully written. A simple time.sleep is unreliable and slows down tests. Instead, poll the file system for the expected file.

A common approach is to use WebDriverWait combined with a custom condition that checks for the file's existence and stability:

python
import os import time from selenium.webdriver.support.ui import WebDriverWait def wait_for_download(driver, download_dir, filename, timeout=30): file_path = os.path.join(download_dir, filename) def file_ready(_): if not os.path.exists(file_path): return False # Check that the file size is stable (i.e., not still growing) size1 = os.path.getsize(file_path) time.sleep(0.5) size2 = os.path.getsize(file_path) return size1 == size2 and size1 > 0 WebDriverWait(driver, timeout).until(file_ready) return file_path

This function polls every 0.5 seconds until the file exists and its size stops changing. It handles both the appearance of the file and the completion of the write. For large files, you may need to increase the timeout.

If you are unsure of the exact filename, you can watch the directory for any new file matching a pattern:

python
def wait_for_any_download(driver, download_dir, timeout=30): before = set(os.listdir(download_dir)) def new_file_appeared(_): after = set(os.listdir(download_dir)) return after - before new_files = WebDriverWait(driver, timeout).until(new_file_appeared) return os.path.join(download_dir, list(new_files)[0])

Note that some browsers append a .crdownload or .part extension while downloading. You may need to filter those out or wait for the final extension to appear.

Taking Element and Full-Page Screenshots

Screenshots are essential for visual regression testing or for capturing evidence of a state. Selenium provides two primary methods: save_screenshot for the current viewport, and element.screenshot for a specific element.

python
# Current viewport screenshot driver.save_screenshot("viewport.png") # Element screenshot element = driver.find_element(By.ID, "result") element.screenshot("element.png")

For full-page screenshots that include content below the fold, you need to adjust the window size or use a scrolling strategy. One common technique is to resize the browser window to the full document height before capturing:

python
def full_page_screenshot(driver, path): original_size = driver.get_window_size() required_width = driver.execute_script("return document.body.parentNode.scrollWidth") required_height = driver.execute_script("return document.body.parentNode.scrollHeight") driver.set_window_size(required_width, required_height) driver.save_screenshot(path) driver.set_window_size(original_size["width"], original_size["height"])

This works for most static pages. Dynamic content that loads on scroll may require additional handling; consider using a dedicated full-page screenshot library or a headless browser with a larger viewport.

Handling Headless Mode and Browser Preferences

When running tests in headless mode, downloads and screenshots behave differently. Headless Chrome and Firefox still support downloads, but you must ensure the download directory is set correctly and that the browser does not prompt for confirmation. The preferences shown earlier work in headless mode, but you may need to add --headless=new for Chrome and -headless for Firefox.

python
options = webdriver.ChromeOptions() options.add_argument("--headless=new") # ... download preferences

For screenshots, headless mode often has a default viewport size that may not match your desktop browser. You can set the window size explicitly:

python
options.add_argument("--window-size=1920,1080")

This ensures that your screenshots have consistent dimensions. Note that in headless mode, set_window_size may not work as expected, so it is better to set the size via command-line arguments.

Common Pitfalls and Runtime Considerations

Several issues frequently arise when combining upload, download, and screenshot operations in a single Selenium script.

Hidden file inputs: If the upload button is a custom widget, the actual <input type="file"> may be hidden. send_keys works on hidden inputs, but you must ensure the element is not disabled. If the input is outside the viewport, Selenium may still interact with it, but some browsers require the element to be visible. In such cases, use JavaScript to remove the display:none style or use element.send_keys directly without clicking.

Download directory permissions: The browser process must have write access to the download directory. Running tests as a non-privileged user can cause silent failures where the file is not saved. Always verify that the directory exists and is writable before starting the test.

Screenshot timing: Screenshots capture the current state of the page. If you need to capture a state after a download or upload, wait for the page to update using explicit waits on expected conditions, not just time.sleep. For example, after clicking an upload button, wait for a success message to appear before taking a screenshot.

Concurrency and isolation: When running tests in parallel, each test should use its own download directory and screenshot filename to avoid conflicts. Use unique paths based on test names or timestamps.

Browser-specific behavior: Chrome and Firefox have different download preference keys. If your test suite runs on multiple browsers, abstract the download configuration behind a factory method that returns the appropriate options object for each browser.

Resource cleanup: Always quit the driver in a finally block or use a context manager to avoid leaving browser processes running, especially when tests fail. This is also important for releasing file locks on downloaded files.

python
try: # test steps except Exception: driver.save_screenshot("failure.png") raise finally: driver.quit()

By handling these runtime details, you can build reliable automation scripts that consistently handle file uploads, downloads, and screenshots across different environments.

Try matching browser tools

All tools

Small utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Python guides

More in Python

All Python guides

The guides filed next to this one in Python, in library order.