Selenium × Python Setup Guide [5 Minutes] | pytest + webdriver-manager, No More Version Errors

This is a complete guide to setting up Selenium × Python — from scratch to passing tests — written so even beginners can get it done in 5 minutes.

👉 Copy the code in this article and your tests will be running in 5 minutes.

“ChromeDriver version mismatch.” “Stuck on environment setup.” — this guide solves both.

This article walks through a production-ready setup using Selenium, webdriver-manager, and pytest — the fastest path to running tests without errors.

👉 vs Playwright: Selenium operates browsers via WebDriver and is the industry standard with far more job postings and client projects than Playwright.

The two most common Selenium setup failures are “ChromeDriver version doesn’t match” and “PATH not configured.” This guide uses webdriver-manager to automate version management entirely — so you won’t hit either of those walls.

Selenium × Python Setup: Full Overview

Here’s the complete flow before diving in.

STEP 1: Verify Python Version (Selenium Python Setup Prerequisite)

First, confirm Python is installed.

python --version
# or
python3 --version

Expected output:

Python 3.11.5

STEP 2: Create and Activate a Virtual Environment (venv) [Python Environment Setup]

Virtual environments keep package dependencies isolated per project. Always use one in production.

Create the virtual environment

# Create project folder
mkdir selenium-project
cd selenium-project

# Create virtual environment
python -m venv venv

Activate the virtual environment

Once activated, your prompt will show (venv) at the start.

(venv) $ 

STEP 3: Install Selenium, webdriver-manager, and pytest (Selenium Python Installation)

With Selenium 4, webdriver-manager automates ChromeDriver version management. No manual downloads required.

pip install selenium webdriver-manager pytest

Verify the installation:

pip list | grep -E "selenium|webdriver|pytest"

# Expected output
pytest             7.4.0
selenium           4.18.1
webdriver-manager  4.0.1

STEP 4: Set Up Project Structure (pytest Structure)

Set up a clean project structure from the start.

selenium-project/
├── venv/                  # virtual environment (don't commit to Git)
├── tests/
│   ├── conftest.py        # fixture definitions
│   └── test_sample.py     # test file
├── requirements.txt       # package list
└── pytest.ini            # pytest config

Create pytest.ini

[pytest]
testpaths = tests
addopts = -v

STEP 5: Configure Selenium WebDriver (conftest.py)

Centralizing WebDriver initialization and teardown in a conftest.py fixture is the production best practice.

# tests/conftest.py
import pytest
from selenium import webdriver
from selenium.webdriver.chrome.service import Service
from webdriver_manager.chrome import ChromeDriverManager

@pytest.fixture(scope="function")
def driver():
    """Fixture that launches and quits Chrome WebDriver"""
    options = webdriver.ChromeOptions()
    # options.add_argument("--headless")  # Recommended OFF at first (see browser in action)
    # Turn this ON for CI/CD environments
    options.add_argument("--no-sandbox")            # For Linux/CI (not needed locally)
    options.add_argument("--disable-dev-shm-usage") # For Linux/CI (not needed locally)
    options.add_argument("--window-size=1920,1080")

    service = Service(ChromeDriverManager().install())
    driver = webdriver.Chrome(service=service, options=options)

    yield driver  # test runs here

    driver.quit()  # close browser after test

STEP 6: Write and Run the Verification Test (pytest)

We’ll use example.com for the verification test — it’s far more stable than Google, which can trigger CAPTCHAs or redirects depending on your region.

# tests/test_sample.py
from selenium.webdriver.common.by import By
from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.support import expected_conditions as EC

def test_example_title(driver):
    """Verify example.com title is retrieved correctly"""
    driver.get("https://example.com")
    assert "Example Domain" in driver.title

def test_example_heading(driver):
    """Wait for heading to be visible, then verify (production-level pattern)"""
    driver.get("https://example.com")
    # WebDriverWait: wait up to 10s until the element is visible (production standard)
    # visibility_of_element_located = in DOM AND visible on screen
    heading = WebDriverWait(driver, 10).until(
        EC.visibility_of_element_located((By.TAG_NAME, "h1"))
    )
    assert heading.is_displayed()

Run the tests

pytest

Sample output

========================== test session starts ==========================
platform darwin -- Python 3.11.5, pytest-7.4.0, selenium-4.18.1
collected 2 items

tests/test_sample.py::test_example_title    PASSED  [ 50%]
tests/test_sample.py::test_example_heading  PASSED  [100%]

========================== 2 passed in 3.21s ===========================

⚠️ Common Errors and Solutions

# Solution: webdriver-manager handles this automatically
# If the cache is stale, upgrade it
pip install --upgrade webdriver-manager

# Solution: activate the virtual environment first, then reinstall
source venv/bin/activate  # Mac/Linux
venv\Scripts\activate     # Windows
pip install selenium webdriver-manager

# NG — missing test_ prefix
def check_example(driver):

# OK
def test_example_title(driver):

from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.support import expected_conditions as EC
from selenium.webdriver.common.by import By

# Wait up to 10 seconds until the element is visible
element = WebDriverWait(driver, 10).until(
    EC.visibility_of_element_located((By.TAG_NAME, "h1"))
)

Selenium vs Playwright: Which Should You Use?

For anyone deciding between the two:

FAQ

Follow this guide step by step and you won’t get stuck on environment setup.

📋 Summary

Once those 2 tests show PASSED, your environment is ready. From here, add more test cases and work toward login form testing and the Page Object Model pattern as your next steps.