HBrowser (hbrowser)

Setup

Tor Proxy (Optional)

HBrowser can route all traffic through the Tor network for IP privacy. If Tor Browser is installed, HBrowser will automatically detect and use it. To install:

Download and install from https://www.torproject.org/download/
HBrowser will automatically locate the tor binary from the default installation path:
- macOS: /Applications/Tor Browser.app/Contents/MacOS/Tor/tor
- Linux: /usr/bin/tor
- Windows: Searches common installation paths (Desktop, AppData, Program Files)
If Tor Browser is not installed, HBrowser will use a direct connection instead.
To force disable Tor even when installed, set USE_TOR=0.
If your Tor Browser is installed in a non-standard location, set the TOR_BINARY_PATH environment variable.

FlareSolverr (Optional)

HBrowser can use FlareSolverr to automatically solve both Cloudflare's page-level managed challenge and the Turnstile widget embedded in the Forums login form. Embedded Turnstile support requires FlareSolverr 3.5.0 or newer. Set FLARESOLVERR_URL to the instance's /v1 endpoint, for example http://127.0.0.1:8191/v1.

HBrowser keeps one persistent FlareSolverr browser across the managed challenge and login Turnstile so both steps use the same browser identity and clearance. That identity must also share the automated browser's public route. HBrowser therefore disables FlareSolverr when Tor or a residential proxy is active unless a future integration can configure the same sticky route on both browsers.

Environment Variables

HBrowser requires the following environment variables:

EH_USERNAME: Your E-Hentai account username
EH_PASSWORD: Your E-Hentai account password
HBROWSER_LOG_LEVEL (optional): Control logging verbosity (DEBUG, INFO, WARNING, ERROR). Default: INFO
HBROWSER_LOG_DIR (optional): Store HTML failure diagnostics in this directory. Default: a log directory next to the main script
HBROWSER_PROCESS_LOG_FILE (optional): Mirror all HBrowser-family logger records to this UTF-8 file. The file rotates at 10 MiB with five backups; applications should leave it unset when an external supervisor already captures stdout/stderr
USE_TOR (optional): Set to 0 to disable Tor proxy even when Tor Browser is installed. Default: auto-detect
TOR_BINARY_PATH (optional): Custom path to the tor binary if not installed in the default location
FLARESOLVERR_URL (optional): FlareSolverr 3.5.0+ /v1 endpoint used to auto-solve Cloudflare managed challenges and the Forums login Turnstile. Ignored when Tor or a residential proxy is active

Set the environment variables before running the script:

Bash/Zsh:

export EH_USERNAME=your_username
export EH_PASSWORD=your_password
export HBROWSER_LOG_LEVEL=INFO          # Optional
export HBROWSER_LOG_DIR=/path/to/log    # Optional: shared diagnostic directory
export USE_TOR=0                        # Optional: disable Tor proxy
export TOR_BINARY_PATH=/path/to/tor     # Optional: custom tor path
export FLARESOLVERR_URL=http://127.0.0.1:8191/v1  # Optional: auto-solve Cloudflare

Fish:

set -x EH_USERNAME your_username
set -x EH_PASSWORD your_password
set -x HBROWSER_LOG_LEVEL INFO          # Optional
set -x USE_TOR 0                        # Optional: disable Tor proxy
set -x TOR_BINARY_PATH /path/to/tor     # Optional: custom tor path
set -x FLARESOLVERR_URL http://127.0.0.1:8191/v1  # Optional: auto-solve Cloudflare

Windows Command Prompt:

set EH_USERNAME=your_username
set EH_PASSWORD=your_password
set HBROWSER_LOG_LEVEL=INFO
set USE_TOR=0
set TOR_BINARY_PATH=C:\path\to\tor.exe
set FLARESOLVERR_URL=http://127.0.0.1:8191/v1

Windows PowerShell:

$env:EH_USERNAME="your_username"
$env:EH_PASSWORD="your_password"
$env:HBROWSER_LOG_LEVEL="INFO"
$env:USE_TOR="0"
$env:TOR_BINARY_PATH="C:\path\to\tor.exe"
$env:FLARESOLVERR_URL="http://127.0.0.1:8191/v1"

When a Cloudflare or CAPTCHA challenge appears during login, HBrowser will first try FlareSolverr (if configured and applicable), then fall back to waiting for you to solve it manually in the browser window. Set headless=False when initialising the driver to see the browser window.

Logging

HBrowser uses Python's built-in logging module. You can control the log level using the HBROWSER_LOG_LEVEL environment variable:

DEBUG: Detailed information for diagnosing problems (most verbose)
INFO: Confirmation that things are working as expected (default)
WARNING: Something unexpected happened, but the software is still working
ERROR: A serious problem that prevented a function from executing

Example:

# Set log level to DEBUG for detailed output
export HBROWSER_LOG_LEVEL=DEBUG
python your_script.py

# Set log level to WARNING to see only warnings and errors
export HBROWSER_LOG_LEVEL=WARNING
python your_script.py

Applications without an external process-log supervisor can also request a rotating text file for HBrowser-family logger records:

export HBROWSER_PROCESS_LOG_FILE=/private/path/battle.log

One file handler is shared by all HBrowser, HVBrowser, and HVBattle loggers in the process, so each record is written once. Existing targets must be regular, single-link files rather than symbolic links. The handler verifies that the configured path still names its open file before and after each record. Where the platform provides them, opening also uses O_NOFOLLOW and O_CLOEXEC; on POSIX, active and rotated files use owner-only permissions. Open, write, path replacement, and rollover failures are raised to the logging caller instead of being silently ignored.

This optional handler records logger output only. It does not capture arbitrary stdout/stderr, subprocess output, or exceptions raised before logging is configured, and it does not provide an fsync-based process transcript. Use an external checked supervisor when those guarantees or terminal fail-closed behavior are required. The parent directory remains part of the application's trust boundary, and Windows file confidentiality depends on its inherited ACLs.

On browser failures, HBrowser saves uniquely named HTML diagnostics instead of overwriting a single error.txt. Page diagnostics and search diagnostics each retain at most 20 files and 20 MiB total, with each file capped at 2 MiB. On POSIX systems these files are created with owner-only permissions. Because page HTML can still contain account-specific data, keep HBROWSER_LOG_DIR in a private location.

Usage

Gallery searches use an explicit request and return a bounded, ordered result. An exact GID lookup only reports a missing gallery after two independent empty searches:

import asyncio

from hbrowser import (
    ConfirmedGalleryMissing,
    ExHDriver,
    GalleryFound,
    SearchRequest,
)


async def main() -> None:
    async with ExHDriver() as driver:
        result = await driver.search(
            SearchRequest(
                scope_url="https://exhentai.org/",
                query="artist:test",
            )
        )
        print(result.galleries, result.pages_visited)

        match await driver.lookup_gid(349189):
            case GalleryFound(gallery=gallery):
                print(gallery.url)
            case ConfirmedGalleryMissing(confirmations=confirmations):
                print(f"Missing after {confirmations} confirmations")


if __name__ == "__main__":
    asyncio.run(main())

HentaiVerse automation is provided separately by HVBrowser.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

hbrowser-0.35.4.tar.gz (90.1 kB view details)

Uploaded Aug 4, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

hbrowser-0.35.4-py3-none-any.whl (75.5 kB view details)

Uploaded Aug 4, 2026 Python 3

File details

Details for the file hbrowser-0.35.4.tar.gz.

File metadata

Download URL: hbrowser-0.35.4.tar.gz
Upload date: Aug 4, 2026
Size: 90.1 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for hbrowser-0.35.4.tar.gz
Algorithm	Hash digest
SHA256	`0a947772e49914218d6b6cbc90f0c871320ba540b50991ffc24e37d8009ee29f`
MD5	`320ebf4babbdca039843564096ccb563`
BLAKE2b-256	`c24688d0b078264640cafec2466269846d6b7ed1e1771cb35c65a2a8fa6e9b13`

See more details on using hashes here.

Provenance

The following attestation bundles were made for hbrowser-0.35.4.tar.gz:

Publisher: publish.yml on Kuan-Lun/hbrowser

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: hbrowser-0.35.4.tar.gz
- Subject digest: 0a947772e49914218d6b6cbc90f0c871320ba540b50991ffc24e37d8009ee29f
- Sigstore transparency entry: 2339676035
- Sigstore integration time: Aug 4, 2026
Source repository:
- Permalink: Kuan-Lun/hbrowser@2fd6d57eaf803b1cd2604cdf4c634ded82750f25
- Branch / Tag: refs/heads/master
- Owner: https://github.com/Kuan-Lun
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish.yml@2fd6d57eaf803b1cd2604cdf4c634ded82750f25
- Trigger Event: push