How to Minimize a Browser Window in Selenium WebDriver

In Selenium 4 and later, minimize the current browser window with the window-management API:

driver.minimize_window()

The command asks the operating system’s window manager to minimize the browser window. Its visible effect depends on that window manager; it typically hides the window. It does not mean “make the page viewport smaller,” and it does not guarantee the same taskbar or system-tray result on every platform. Selenium’s window guide documents the operation and its platform-dependent behavior.

Python: minimize a window

This runnable example opens a page, minimizes the current window, and quits cleanly. Install Selenium with python -m pip install selenium; Selenium Manager can manage the browser driver for supported setups.

from selenium import webdriver

options = webdriver.ChromeOptions()
driver = webdriver.Chrome(options=options)

try:
    driver.get("https://example.com")
    driver.minimize_window()
finally:
    driver.quit()

The Python API describes minimize_window() as invoking the window-manager-specific minimize operation; it returns None. See the Python WebDriver API reference.

Syntax in Java, JavaScript, C#, Ruby, and Kotlin

Use the binding’s window-management syntax. In JavaScript, await the returned promise.

WebDriver driver = new ChromeDriver();
driver.get("https://example.com");
driver.manage().window().minimize();

const { Builder } = require('selenium-webdriver');

(async function () {
  const driver = await new Builder().forBrowser('chrome').build();
  try {
    await driver.get('https://example.com');
    await driver.manage().window().minimize();
  } finally {
    await driver.quit();
  }
})();

IWebDriver driver = new ChromeDriver();
driver.Navigate().GoToUrl("https://example.com");
driver.Manage().Window.Minimize();

driver = Selenium::WebDriver.for :chrome
driver.navigate.to "https://example.com"
driver.manage.window.minimize

val driver = ChromeDriver()
driver.get("https://example.com")
driver.manage().window().minimize()

These language forms are documented in Selenium’s official window-management guide. Ensure the installed Selenium binding supports Selenium 4’s window operations.

What gets minimized?

The command applies to the current browsing context. WebDriver does not treat tabs and windows as separate categories for handle switching, so if your script has multiple windows, switch to the intended handle before minimizing.

handles = driver.window_handles

# Example: select a known target handle before minimizing.
target_handle = handles[-1]
driver.switch_to.window(target_handle)
driver.minimize_window()

Do not assume the last handle is always the desired one: select by a condition that matches your test, such as the URL or page title, when window order can vary.

Minimize versus resize, maximize, and fullscreen

Intent	Operation	Effect
Ask the window manager to hide the current browser window	minimize_window()	Platform-dependent minimized state
Use the available desktop area	maximize_window()	Maximized window geometry
Enter fullscreen mode	fullscreen_window()	Fullscreen window state
Set a specific window size	set_window_size(width, height)	Requested window dimensions

Choose the operation that matches what the test needs to verify. If the goal is a particular page viewport for layout checks or screenshots, set a size rather than minimizing. Browser window geometry and the page’s usable viewport are related but not identical.

Local, headless, and remote sessions

• Local headed browser: the browser runs on your machine. The desktop’s window manager determines how minimize appears, commonly hiding the window.
• Headless browser: there may be no visible desktop window to minimize. Do not rely on a visible tray or taskbar change; use viewport sizing for layout behavior.
• Remote WebDriver or Grid: commands control a browser on a remote machine or through a Selenium server. Any visible effect belongs to that remote environment. A local desktop change is not guaranteed.

Selenium’s remote documentation describes WebDriver as controlling a browser remotely; the reviewed documentation does not promise a local visual effect from a remote minimize call. Treat the outcome as environment-dependent.

Common errors and fixes

Symptom	Likely cause	Fix
Method is missing or not recognized	An older Selenium binding is installed, or the call uses another language’s syntax.	Upgrade to Selenium 4 or later and use the binding-specific example above.
The wrong browser window disappears	The script minimized whichever browsing context was active.	Switch to the intended window handle immediately before calling minimize.
Nothing appears to happen	The session is headless, remote, or running under a window manager with different behavior.	Check the browser host and execution mode. Use resizing if the actual requirement is viewport geometry.
Window state command fails in CI	The CI environment may not provide a desktop window manager, or the browser/session may not support a visible window operation.	Run headed with a supported display environment if minimizing is under test; otherwise test the desired page behavior without relying on minimization.
Later page interactions fail	The browser is minimized and the test depends on foreground visibility or desktop interaction.	Restore or maximize the window before those steps, or avoid minimizing in tests that require visible interaction.

Reliability, performance, and cost notes

Minimization is a window-manager operation, not a page-loading optimization. It does not guarantee lower CPU or memory use, stop JavaScript, or change network requests. Its timing and visible outcome can vary with operating system, desktop environment, browser mode, and remote execution setup. Avoid making assertions about a specific tray icon or taskbar appearance unless the test controls that environment.

For stable automated tests, prefer checking browser-visible state and setting an explicit viewport when geometry matters. Selenium itself is an automation library; browser hosting, Grid capacity, and CI costs depend on your environment and are not determined by this command.

Or skip the browser setup

If your actual goal is to get a page screenshot rather than test Selenium’s window state, ScreenshotNeo is a website screenshot API and MCP server for developers. One GET request returns an image or PDF; see the API documentation.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
const fs = require('node:fs/promises');
await fs.writeFile('shot.webp', Buffer.from(await res.arrayBuffer()));

ScreenshotNeo removes supported cookie and consent banners, newsletter popups, and chat widgets before the capture. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and response headers identify the page verdict and billing status. Its MCP server lets AI agents use screenshot, page-info, and PDF tools. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Sign up for 1,000 free screenshots a month, with no card required.

FAQ

Does minimizing close the browser?

No. It requests a minimized window state; it does not quit the WebDriver session.

Can I minimize just one tab?

The operation applies to the current browsing context’s window. Switch to the relevant handle if multiple windows are open.

Is minimize available in Selenium 3?

The official guide documents this operation for Selenium 4 and later. Upgrade the binding if the method is unavailable.

Will a minimized browser keep running?

Minimizing does not itself terminate the browser or WebDriver session. Whether page activity continues as expected depends on the browser and environment.