For many Selenium 3 projects, upgrading starts with changing the binding dependency. Before calling the migration complete, check that your capabilities use the W3C WebDriver format, resolve deprecated or binding-specific APIs, and run the suite against the browsers and environments you support. Selenium says W3C-compliant code from late Selenium 3 should work as expected in Selenium 4, but code relying on deprecated or internal APIs may need changes.
The official Selenium downloads page lists Selenium 4.49.0 as stable for the core bindings and Grid, with the binding release dated September 9, 2026. Releases continue to change, so check the downloads page and release notes when you upgrade.
As an Amazon Associate I earn from qualifying purchases.
Plan the migration before changing dependencies
Record the versions and configuration the current test suite depends on. This makes failures after the upgrade easier to distinguish from existing environment problems.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
- The Selenium binding version and language/runtime version.
- Supported browser versions and whether they are pinned or allowed to update.
- How browser drivers are installed or discovered.
- Whether tests use a local browser, Selenium Grid, or a cloud WebDriver service.
- Any custom capabilities, deprecated methods, or code that reaches into Selenium internals.
The official Selenium 4 migration guide covers dependency updates for Java, C#, Python, Ruby, and JavaScript. Its sample package versions are historical; use the version appropriate to your project and check the current release information instead.
#1 Best Overall
Upgrade the binding, then build and test
- Update the Selenium dependency using your project’s package manager and version policy. As of September 9, 2026, the downloads page lists 4.49.0 for Java, .NET/C#, Python, Ruby, JavaScript, and Server/Grid.
- Compile or build the project. Fix errors caused by changed or removed APIs before making other changes.
- Run a small, representative test locally. Include a test that starts a browser session and exercises any remote or custom-capability path your suite uses.
- Run the full suite across your supported browser, runtime, and CI matrix. Check the release notes for the exact Selenium minor version you selected.
The Selenium 4 launch guidance said that users already on Selenium could often start by changing the dependency, while warning that use of deprecated or internal APIs might cause problems. Selenium 4.49, for example, removed a deprecated Java file endpoint, so the API surface can change within the Selenium 4 series. See the Selenium 4 announcement and Selenium 4.49 release notes.
Check capabilities if sessions stop starting
Selenium 4 uses the W3C WebDriver protocol; it no longer supports the legacy JSON Wire Protocol. A capability structure that worked with an older setup can therefore prevent session creation after an upgrade.
Use W3C standard capability names
Use standard names such as browserName, browserVersion, platformName, acceptInsecureCerts, pageLoadStrategy, proxy, timeouts, and unhandledPromptBehavior. In particular, use browserVersion rather than the old version name, and platformName rather than platform.
Free tools Windows power users keep installed
One-click scans. No signup required.
Keep provider-specific options in the provider’s format
Browser vendors and cloud services may require additional capabilities. Use the prefix, nesting, and exact key names documented by the provider; the Selenium guide illustrates vendor-specific values grouped under a block such as cloud:options, but that example does not define every provider’s syntax. Consult the migration guide and the documentation for the service you use.
Rank #2
Resolve binding-specific API changes
These examples are changes documented in Selenium’s migration guide, not a complete list for every Selenium 4 release. Check the API reference for your target version when a compiler or runtime error points to another changed method.
Java
Timeout-related APIs that previously accepted a long and TimeUnit use Duration in the guide’s examples. This applies to WebDriver timeouts and to WebDriverWait, withTimeout, and pollingEvery.
When using FirefoxOptions.merge, assign its returned options object rather than assuming the original object is updated:
FirefoxOptions options = new FirefoxOptions();
options = options.merge(capabilities);The guide also marks legacy Firefox mode as deprecated and BrowserType as deprecated in favor of Browser.
C#
For the options case shown in the migration guide, replace deprecated AddAdditionalCapability usage with AddAdditionalOption. Confirm the method signature and accepted option structure for the relevant browser and Selenium version.
Python
Pass a Service object when specifying a driver executable instead of passing executable_path directly to driver construction. Alternatively, make the driver executable available on PATH. For example, with Chrome:
from selenium import webdriver
from selenium.webdriver.chrome.service import Service
service = Service("/path/to/chromedriver")
driver = webdriver.Chrome(service=service)
try:
driver.get("https://example.com")
print(driver.title)
finally:
driver.quit()The path above is an example; supply the executable location for your environment, or omit the explicit service configuration when relying on driver discovery.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Ruby and JavaScript
Update the selenium-webdriver gem or package using the package manager and dependency policy for the project. Do not copy the older pinned versions shown in the migration guide as current recommendations; check the current downloads page and your package manager’s version requirements.
Decide how Selenium will find browser drivers
Selenium Manager is Selenium’s official driver-management component. It has shipped with Selenium releases since 4.6 and is used as a fallback when a binding cannot find a driver. You can also retain manual management through PATH or system properties, or continue using a third-party manager. Selenium documents these choices in its Selenium Manager documentation.
| Approach | Operational fit | What to validate |
|---|---|---|
| Manual provisioning | Useful when your team pins and installs browser drivers as part of its environment. | Confirm the driver is available at the configured path in developer environments, CI, and containers. |
| Selenium Manager fallback | Lets Selenium attempt driver management when a driver is not already found. | Test discovery and session startup in each environment where the suite runs. |
| Existing third-party manager | Can remain in place if it is part of the project’s established setup. | Check that its driver selection and configuration still match the browser versions under test. |
The right choice depends on your local and CI setup, and on whether browser versions are pinned or move over time. The Selenium documentation describes the available approaches but does not prescribe one for every team.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Troubleshoot common upgrade failures
The WebDriver session will not start
Inspect the capabilities sent to the browser or remote service. Replace legacy names such as version and platform with W3C names, and confirm provider-specific keys use the exact prefix and nesting the service requires.
Recommended Free Tools
The project no longer compiles
Use the compiler error to locate APIs that changed or were deprecated. Apply the binding-specific updates above, then check the migration guide and API reference for the target version rather than assuming every Selenium 4 release has identical APIs.
Python rejects executable_path
Replace that driver-construction argument with a Service object, or make the executable discoverable through PATH.
The browser launches locally but not in CI
Check driver availability and browser/driver compatibility in the CI image. If using Selenium Manager, verify that the binding can use its fallback in that environment; if using manual or third-party management, confirm the configured executable is present in the job or container.
A remote or cloud session is rejected
Compare the full capability payload with the provider’s current WebDriver instructions. Standard W3C capabilities and provider-specific options have different naming and nesting rules.
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Repair Windows errors before they cause bigger problems3Fix the driver behind crashes, sound loss and screen glitchesExplore Selenium 4 features after the suite passes
Relative locators are optional; they are not required to migrate. They let a test locate an element by its position relative to a known element, using relationships such as above, below, or beside. Selenium determines positions and sizes using browser geometry. See the Selenium locator strategies documentation before adopting them in tests.
Or skip the browser setup
If your immediate task is to capture a webpage rather than migrate browser automation, ScreenshotNeo provides a website screenshot API and MCP server for developers. A single GET request can return a PNG, JPEG, WebP, or PDF. For example, using cURL:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for request options. It accepts cookie and consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each of those steps can be turned off. Bot checks/CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and responses indicate the page verdict and billing status in headers. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for AI agents. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 screenshots.
Sign up for ScreenshotNeo’s free plan.
Frequently Asked Questions
Do I need to rewrite every Selenium 3 test to use Selenium 4?
No. Selenium says W3C-compliant code from late Selenium 3 should work as expected in Selenium 4; review and change code that uses deprecated APIs, internals, or incompatible capabilities.
Is Selenium Manager mandatory after upgrading?
No. It is a fallback option; manual driver provisioning and third-party managers remain possible.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
