BrowserForge

🎭 Intelligent browser header & fingerprint generator

What is it?

BrowserForge is a browser header and fingerprint generator that mimics the frequency of different browsers, operating systems, and devices found in the wild.

It is a reimplementation of Apify's fingerprint-suite in Python.

Features

• Uses a Bayesian generative network to mimic actual web traffic
• Extremely fast runtime (0.1-0.2 miliseconds)
• Easy and simple for humans to use
• Extensive customization options for browsers, operating systems, devices, locales, and HTTP version
• Written with type safety

Installation

pip install browserforge[all]
python -m browserforge update

The [all] extra will include optional libraries like orjson.

Use python -m browserforge update to fetch necessary model files. If the command is not run, files will be downloaded on the first import.

Usage

Generating Headers

Simple usage

>>> from browserforge.headers import HeaderGenerator
>>> headers = HeaderGenerator()
>>> headers.generate()
{'sec-ch-ua': '"Chromium";v="122", "Not(A:Brand";v="24", "Google Chrome";v="122"', 'Sec-Ch-Ua-Mobile': '?0', 'Sec-Ch-Ua-Platform': '"Windows"', 'Upgrade-Insecure-Requests': '1', 'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.0.0 Safari/537.36', 'Accept': 'text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.7', 'Sec-Fetch-Site': '?1', 'Sec-Fetch-Mode': 'same-site', 'Sec-Fetch-User': 'document', 'Sec-Fetch-Dest': 'navigate', 'Accept-Encoding': 'gzip, deflate, br, zstd', 'Accept-Language': 'en-US;q=1.0'}

Using with requests

Headers can be added to a session in requests (or similar libraries) by assigning them to the headers attribute:

import requests
session = requests.Session()
# Set the session headers
session.headers = headers.generate()

Constraining headers

Single constraint

Set constraints for browsers by passing the optional strings below:

headers = HeaderGenerator(
    browser='chrome',
    os='windows',
    device='desktop',
    locale='en-US',
    http_version=2
)

Multiple constraints

Set multiple constraints to select from. Options are selected based on their actual frequency in the wild:

headers = HeaderGenerator(
    browser=('chrome', 'firefox', 'safari', 'edge'),
    os=('windows', 'macos', 'linux', 'android', 'ios'),
    device=('desktop', 'mobile'),
    locale=('en-US', 'en', 'de'),
    http_version=2
)

Browser specifications

Set specificiations for browsers, including version ranges and HTTP version:

from browserforge.headers import Browser

browsers = [
    Browser(name='chrome', min_version=100, max_version=110),
    Browser(name='firefox', max_version=80, http_version=1),
    Browser(name='edge', min_version=95),
]
headers = HeaderGenerator(browser=browsers)

Note that all constraints passed into the HeaderGenerator constructor can be overridden by passing them into the generate method.

Generate headers given User-Agent

Headers can be generated given an existing user agent:

>>> headers.generate(user_agent='Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36')

Select from multiple User-Agents based on their frequency in the wild:

>>> headers.generate(user_agent=(
    'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36',
    'Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:109.0) Gecko/20100101 Firefox/115.0'
))

Generating Fingerprints

Simple usage

Initialize FingerprintGenerator:

from browserforge.fingerprints import FingerprintGenerator
fingerprints = FingerprintGenerator()
fingerprints.generate()

Constraining fingerprints

Screen width/height

Constrain the minimum/maximum screen width and height:

from browserforge.fingerprints import Screen

screen = Screen(
    min_width=100
    max_width=1280
    min_height=400
    max_height=720
)

fingerprints = FingerprintGenerator(screen=screen)

Note: Not all bounds need to be defined.

Browser specifications

FingerprintGenerator and FingerprintGenerator.generate inherit the same parameters from HeaderGenerator.

Because of this, user agents, browser specifications, device types, and operating system constrains can also be passed into FingerprintGenerator.generate.

Here is a usage example:

fingerprint.generate(browser='chrome', os='windows')

Injecting Fingerprints

BrowserForge is fully compatible with your existing Playwright and Pyppeteer code. You only have to change your context/page initialization.

Playwright

Async API:

# Import the AsyncNewContext injector
from browserforge.injectors.playwright import AsyncNewContext

async def main():
    async with async_playwright() as playwright:
        browser = await playwright.chromium.launch()
        # Create a new async context with the injected fingerprint
        context = await AsyncNewContext(browser, fingerprint=fingerprint)
        page = await context.new_page()
        ...

Replace await browser.new_context with await AsyncNewContext in your existing Playwright code.

Sync API:

# Import the NewContext injector
from browserforge.injectors.playwright import NewContext

def main():
    with sync_playwright() as playwright:
        browser = playwright.chromium.launch()
        # Create a new context with the injected fingerprint
        context = NewContext(browser, fingerprint=fingerprint)
        page = context.new_page()
        ...

Replace browser.new_context with NewContext in your existing Playwright code.

Undetected-Playwright

Undetected-Playwright is also supported in the browserforge.injectors.undetected_playwright package. The usage is the same as the Playwright injector.

Pyppeteer

# Import the NewPage injector
from browserforge.injectors.pyppeteer import NewPage
from pyppeteer import launch

async def test():
    browser = await launch()
    # Create a new page with the injected fingerprint
    page = await NewPage(browser, fingerprint=fingerprint)
    ...

Replace browser.newPage with NewPage in your existing Pyppeteer code.

Uninstall

To fully remove all files, run the following commands:

python -m browserforge remove
pip uninstall browserforge