camoufox 0.2.8

Wrapper around Playwright to help launch Camoufox

Camoufox Python Interface

Lightweight wrapper around the Playwright API to help launch Camoufox.

---

Installation

First, install the camoufox package:

pip install -U camoufox[geoip]

The geoip parameter is optional, but heavily recommended if you are using proxies. It will download an extra dataset to determine the user's longitude, latitude, timezone, country, & locale.

Next, download the Camoufox browser:

Windows

camoufox fetch

MacOS & Linux

python3 -m camoufox fetch

To uninstall, run camoufox remove.

CLI options

Usage: python -m camoufox [OPTIONS] COMMAND [ARGS]...

Options:
  --help  Show this message and exit.

Commands:
  fetch    Fetch the latest version of Camoufox
  path     Display the path to the Camoufox executable
  remove   Remove all downloaded files
  server   Launch a Playwright server
  test     Open the Playwright inspector
  version  Display the current version

---

Usage

Camoufox is fully compatible with your existing Playwright code. You only have to change your browser initialization:

Sync API

from camoufox.sync_api import Camoufox

with Camoufox(headless=False) as browser:
    page = browser.new_page()
    page.goto("https://example.com/")

Async API

from camoufox.async_api import AsyncCamoufox

async with AsyncCamoufox(headless=False) as browser:
    page = await browser.new_page()
    await page.goto("https://example.com")

Parameters

Launches a new browser instance for Camoufox.
Accepts all Playwright Firefox launch options, along with the following:

Parameters:
    config (Optional[Dict[str, Any]]):
        Camoufox properties to use.
    os (Optional[ListOrString]):
        Operating system to use for the fingerprint generation.
        Can be "windows", "macos", "linux", or a list to randomly choose from.
        Default: ["windows", "macos", "linux"]
    block_images (Optional[bool]):
        Whether to block all images.
    block_webrtc (Optional[bool]):
        Whether to block WebRTC entirely.
    allow_webgl (Optional[bool]):
        Whether to allow WebGL. To prevent leaks, only use this for special cases.
    geoip (Optional[Union[str, bool]]):
        Calculate longitude, latitude, timezone, country, & locale based on the IP address.
        Pass the target IP address to use, or `True` to find the IP address automatically.
    humanize (Optional[Union[bool, float]]):
        Humanize the cursor movement.
        Takes either `True`, or the MAX duration in seconds of the cursor movement.
        The cursor typically takes up to 1.5 seconds to move across the window.
    locale (Optional[str]):
        Locale to use in Camoufox.
    addons (Optional[List[str]]):
        List of Firefox addons to use.
    fonts (Optional[List[str]]):
        Fonts to load into Camoufox (in addition to the default fonts for the target `os`).
        Takes a list of font family names that are installed on the system.
    exclude_addons (Optional[List[DefaultAddons]]):
        Default addons to exclude. Passed as a list of camoufox.DefaultAddons enums.
    screen (Optional[Screen]):
        Constrains the screen dimensions of the generated fingerprint.
        Takes a browserforge.fingerprints.Screen instance.
    fingerprint (Optional[Fingerprint]):
        Use a custom BrowserForge fingerprint. Note: Not all values will be implemented.
        If not provided, a random fingerprint will be generated based on the provided
        `os` & `screen` constraints.
    ff_version (Optional[int]):
        Firefox version to use. Defaults to the current Camoufox version.
        To prevent leaks, only use this for special cases.
    headless (Optional[bool]):
        Whether to run the browser in headless mode. Defaults to False.
        WARNING: Please avoid using headless mode until issue #26 is fixed.
    executable_path (Optional[str]):
        Custom Camoufox browser executable path.
    firefox_user_prefs (Optional[Dict[str, Any]]):
        Firefox user preferences to set.
    proxy (Optional[Dict[str, str]]):
        Proxy to use for the browser.
        Note: If geoip is True, a request will be sent through this proxy to find the target IP.
    args (Optional[List[str]]):
        Arguments to pass to the browser.
    env (Optional[Dict[str, Union[str, float, bool]]]):
        Environment variables to set.
    persistent_context (Optional[bool]):
        Whether to use a persistent context.
    debug (Optional[bool]):
        Prints the config being sent to Camoufox.
    **launch_options (Dict[str, Any]):
        Additional Firefox launch options.

---

Config

Camoufox config data can be passed as a dictionary to the config parameter:

from camoufox.sync_api import Camoufox

with Camoufox(
    config={
        'webrtc:ipv4': '123.45.67.89',
        'webrtc:ipv6': 'e791:d37a:88f6:48d1:2cad:2667:4582:1d6d',
    }
) as browser:
    page = browser.new_page()
    page.goto("https://www.browserscan.net/webrtc")

---

GeoIP & Proxy Support

By passing geoip=True, or passing in a target IP address, Camoufox will automatically use the target IP's longitude, latitude, timezone, country, locale, & spoof the WebRTC IP address.

It will also calculate and spoof the browser's language based on the distribution of language speakers in the target region.

Installation

Install Camoufox with the geoip extra:

pip install -U camoufox[geoip]

Usage

Pass in the proxy dictionary as you would with Playwright's proxy parameter:

with Camoufox(
    geoip=True,
    proxy={
        'server': 'http://example.com:8080',
        'username': 'username',
        'password': 'password'
    }
) as browser:
    page = browser.new_page()
    page.goto("https://www.browserscan.net")

---

Remote Server (experimental)

[!WARNING] This feature is experimental and not meant for production use. It uses a hacky workaround to gain access to undocumented Playwright methods.

Launching

To launch a remote server, run the following CLI command:

python -m camoufox server

Or, configure the server with a launch script:

from camoufox.server import launch_server

launch_server(
    headless=True,
    geoip=True,
    proxy={
        'server': 'http://example.com:8080',
        'username': 'username',
        'password': 'password'
    }
)

Connecting

To connect to the remote server, use Playwright's connect method:

from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    # Example endpoint
    browser = p.firefox.connect('ws://localhost:34091/8c7c6cdea3368d937ef7db2277d6647b')
    page = browser.new_page()
    ...

Note: Because servers only use one browser instance, fingerprints will not rotate between sessions. If you plan on using Camoufox at scale, consider rotating the server between sessions.

---

BrowserForge Integration

Camoufox is compatible with BrowserForge fingerprints.

By default, Camoufox will generate an use a random BrowserForge fingerprint based on the target os & screen constraints.

from camoufox.sync_api import Camoufox
from browserforge.fingerprints import Screen

with Camoufox(
    os=('windows', 'macos', 'linux'),
    screen=Screen(max_width=1920, max_height=1080),
) as browser:
    page = browser.new_page()
    page.goto("https://example.com/")

Notes:

• If Camoufox is being ran in headful mode, the max screen size will be generated based on your monitor's dimensions (+15%).

• To prevent UA-spoofing leaks, Camoufox only generates fingerprints with the same browser version as the current Camoufox version by default.

  • If rotating the Firefox version is absolutely necessary, it would be more advisable to rotate between older versions of Camoufox instead.

Injecting custom Fingerprint objects...

[!WARNING] It is recommended to pass os & screen constraints into Camoufox instead. Camoufox will handle fingerprint generation for you. This will be deprecated in the future.

You can also inject your own Firefox BrowserForge fingerprint into Camoufox.

from camoufox.sync_api import Camoufox
from browserforge.fingerprints import FingerprintGenerator

fg = FingerprintGenerator(browser='firefox')

# Launch Camoufox with a random Firefox fingerprint
with Camoufox(fingerprint=fg.generate()) as browser:
    page = browser.new_page()
    page.goto("https://example.com/")

Note: As of now, some properties from BrowserForge fingerprints will not be passed to Camoufox. This is due to the outdated fingerprint dataset from Apify's fingerprint-suite (see here). Properties will be re-enabled as soon as an updated dataset is available.

---