Python Selenium: File Upload, Download, and Screenshots
Learn how to automate file uploads, manage downloads, and capture screenshots with Python Selenium WebDriver.

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.
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:
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:
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:
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:
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_pathThis 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:
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.
# 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:
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.
options = webdriver.ChromeOptions()
options.add_argument("--headless=new")
# ... download preferencesFor screenshots, headless mode often has a default viewport size that may not match your desktop browser. You can set the window size explicitly:
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.
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 toolsSmall utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Python guides
All Python guidesPython iter(): How the Built-in Function Works
Explains Python's iter() built-in: how it creates iterators, the two-argument sentinel form, custom iterator classes, and common edge cases.
Python Pika: Queues, Exchanges, Routing Keys, and Acknowledgements
Learn how to use Python's Pika client with RabbitMQ: declare queues and exchanges, publish with routing keys, consume messages, and handle acknowledgements reliably.
Python Kafka: kafka-python vs Confluent Client
python kafka python vs confluent kafka: Compare kafka-python and Confluent Kafka Python clients: API differences, performance, feature coverage, and when to choose eac...
Python Kafka Offsets, Partitions, and Manual Commits
Learn how Kafka offsets and partitions work and how to manually commit offsets in Python consumers with kafka-python and confluent-kafka. Covers sync vs async commits, rebalances, and seeking.
More in Python
All Python guidesThe guides filed next to this one in Python, in library order.