Implementation:SeleniumHQ Selenium Python Pyproject

Knowledge Sources	SeleniumHQ_Selenium
Domains	WebDriver, Python_Bindings, Package_Management
Last Updated	2026-02-12 00:00 GMT

Overview

The pyproject.toml is the central configuration file for the Selenium Python package, defining build system requirements, package metadata, dependencies, and tool configurations for pytest, mypy, and ruff.

Description

This file uses the PEP 621 standard for Python project metadata and configures multiple aspects of the Selenium Python binding:

Build System: Uses setuptools with setuptools-rust as build backends. The Rust extension module compiles Selenium Manager as a native executable bundled with the package via the tool.setuptools-rust.ext-modules section with binding = "Exec".

Package Metadata:

• Name: selenium
• License: Apache-2.0
• Requires Python >= 3.10
• Supports Python 3.10 through 3.14
• Classifiers indicate Production/Stable status, targeting developers building testing and library software

Dependencies:

• certifi (>= 2026.1.4) - SSL certificate bundle
• trio (>= 0.31.0) - Async I/O framework
• trio-websocket (>= 0.12.2) - WebSocket support for trio
• typing_extensions (>= 4.15.0) - Backported typing features
• urllib3[socks] (>= 2.6.3) - HTTP client with SOCKS proxy support
• websocket-client (>= 1.8.0) - WebSocket client library

Package Discovery: Includes all selenium* packages while excluding test*, with namespace packages enabled. Package data includes Python files, JSON schemas, Firefox XPI extensions, JavaScript atoms, type stubs, and Selenium Manager binaries.

Pytest Configuration: Defines console output style, fault handler timeout, trio mode, custom markers for expected test failures per browser (xfail_chrome, xfail_firefox, etc.), and test file patterns.

Mypy Configuration: Sets strict type-checking options while excluding the auto-generated devtools directory. Currently configured with relaxed settings (many strict flags set to false) with the stated aim to tighten them over time.

Ruff Configuration: Configures the Ruff linter/formatter with line length 120, Python 3.10 target, Google-style docstrings, and selected lint rules (D, E, F, I, PT, UP, RUF, TID252) while excluding the auto-generated devtools directory.

Usage

This file is used by pip install, python -m build, and other PEP 517-compliant build frontends to build and install the Selenium Python package. It is also read by pytest, mypy, and ruff when invoked from the py/ directory.

Code Reference

Source Location

• Repository: SeleniumHQ_Selenium
• File: py/pyproject.toml

Signature

[build-system]
requires = ["setuptools", "setuptools-rust"]
build-backend = "setuptools.build_meta"

[project]
name = "selenium"
version = "4.41.0.202601181916"
license = "Apache-2.0"
requires-python = ">=3.10"
dependencies = [
    "certifi>=2026.1.4",
    "trio>=0.31.0,<1.0",
    "trio-websocket>=0.12.2,<1.0",
    "typing_extensions>=4.15.0,<5.0",
    "urllib3[socks]>=2.6.3,<3.0",
    "websocket-client>=1.8.0,<2.0",
]

[tool.setuptools.packages.find]
include = ["selenium*"]
exclude = ["test*"]
namespaces = true

[[tool.setuptools-rust.ext-modules]]
target = "selenium.webdriver.common.selenium-manager"
binding = "Exec"

Import

# Install the package using the pyproject.toml configuration:
pip install py/

# Or build a distribution:
python -m build py/

I/O Contract

Build System

Key	Value	Description
build-system.requires	setuptools, setuptools-rust	Build dependencies including Rust compilation support
build-system.build-backend	setuptools.build_meta	PEP 517 build backend

Runtime Dependencies

Package	Version Constraint	Purpose
certifi	>= 2026.1.4	Root CA certificates for TLS
trio	>= 0.31.0, < 1.0	Async I/O for BiDi protocol support
trio-websocket	>= 0.12.2, < 1.0	WebSocket transport for async BiDi connections
typing_extensions	>= 4.15.0, < 5.0	Backported type annotation features
urllib3[socks]	>= 2.6.3, < 3.0	HTTP client with SOCKS proxy support for WebDriver commands
websocket-client	>= 1.8.0, < 2.0	Synchronous WebSocket client for CDP/BiDi

Dependency Groups

Group	Packages	Purpose
lint	ruff==0.15.0	Code linting and formatting
validate	validate-pyproject==0.25, packaging==26.0	Pyproject.toml validation

Tool Configuration Summary

Tool	Section	Key Settings
pytest	[tool.pytest]	trio_mode=true, custom xfail markers per browser, test paths = test/
mypy	[tool.mypy]	Excludes devtools, warns on redundant casts and unused ignores
ruff	[tool.ruff]	Line length 120, Python 3.10 target, Google docstrings, extended lint rules

Usage Examples

# Install selenium from source:
pip install ./py/

# Build a wheel distribution:
cd py/ && python -m build --wheel

# Run the linter:
cd py/ && ruff check .

# Run type checking:
cd py/ && mypy selenium/

# Run tests with pytest (using configuration from pyproject.toml):
cd py/ && pytest --driver=chrome --headless

# Adding a new dependency would involve editing the dependencies list:
[project]
dependencies = [
    "certifi>=2026.1.4",
    "trio>=0.31.0,<1.0",
    # ... existing deps ...
    "new-package>=1.0,<2.0",
]

Related Pages

• SeleniumHQ_Selenium_Python_Conftest - Pytest fixtures and test configuration
• SeleniumHQ_Selenium_Python_CDP_Generator - Python CDP binding code generator
• SeleniumHQ_Selenium_SeleniumManager_GetBinaryPaths - Selenium Manager (Rust binary bundled via setuptools-rust)
• SeleniumHQ_Selenium_Format_Sh_Script - Formatting script used before commits