HBLOCK(1)

📦
version 3.5.1 · 2 versions
, in arch rolling, nixos 26.05

✨ hBlock, but make it make sense ✨

okay so bestie, sit down, because this is the hBlock man page (it lives in section 1 of the manual, the User Commands girlies 💅) and honestly? it's kind of iconic. i'm gonna walk you through it like we're on facetime and i'm explaining it with my whole chest 🫶

🌸 SYNOPSIS 🌸

hblock [OPTION]...

like… that's it. you just run hblock and throw options at it. no cap, that's the whole vibe 🎀

💖 DESCRIPTION 💖

so hBlock is a POSIX-compliant shell script — yes, a shell script, she's lowkey humble but she WORKS — and what she does is: she goes and gets a list of domains that serve ads, tracking scripts and malware from multiple sources, and then she creates a hosts file (among other formats, she's versatile like that) that prevents your system from connecting to them. periodt. no ads, no trackers, no malware, literally none 🔥

it's giving protective older sister energy fr fr 🧚

✨ OPTIONS ✨

okay this is the long part, but every single one matters, so stay with me bestie. i'm not skipping a single one, that would be a crime 😭

🎀 the output & content options

  • -O, --output <FILE|->, ${HBLOCK_OUTPUT_FILE} — where the output file goes. if it equals -, it's printed to stdout instead (surprise! it's a stream now 💅). (default: /etc/hosts)
  • -H, --header <FILE|builtin|none|->, ${HBLOCK_HEADER_FILE} — the file that gets included at the beginning of the output file. if it equals builtin, the built-in value is used. if it equals none, an empty value is used. if it equals -, the stdin content is used. and if you leave it unspecified and any of the following files exists, its content is used:
    • ${XDG_CONFIG_HOME}/hblock/header
    • /etc/hblock/header

(default: builtin)

  • -F, --footer <FILE|builtin|none|->, ${HBLOCK_FOOTER_FILE} — same deal but it goes at the end of the output file 🦋. if it equals builtin, the built-in value is used. if it equals none, an empty value is used. if it equals -, the stdin content is used. and if unspecified, and any of these exist, its content is used:
    • ${XDG_CONFIG_HOME}/hblock/footer
    • /etc/hblock/footer

(default: builtin)

  • -S, --sources <FILE|builtin|none|->, ${HBLOCK_SOURCES_FILE} — a file with line separated URLs that are used to generate the blocklist. if it equals builtin, the built-in value is used. if it equals none, an empty value is used. if it equals -, the stdin content is used. if unspecified, and any of these exist, its content is used:
    • ${XDG_CONFIG_HOME}/hblock/sources.list
    • /etc/hblock/sources.list

(default: builtin)

  • -A, --allowlist <FILE|builtin|none|->, ${HBLOCK_ALLOWLIST_FILE} — a file with line separated entries to be removed from the blocklist (the "bestie i prommy this one is fine, let her through" list 💖). if it equals builtin, the built-in value is used. if it equals none, an empty value is used. if it equals -, the stdin content is used. if unspecified, and any of these exist, its content is used:
    • ${XDG_CONFIG_HOME}/hblock/allow.list
    • /etc/hblock/allow.list

(default: builtin)

  • -D, --denylist <FILE|builtin|none|->, ${HBLOCK_DENYLIST_FILE} — a file with line separated entries to be added to the blocklist (the "nope, absolutely not, blocked" list 🚫). if it equals builtin, the built-in value is used. if it equals none, an empty value is used. if it equals -, the stdin content is used. if unspecified, and any of these exist, its content is used:
    • ${XDG_CONFIG_HOME}/hblock/deny.list
    • /etc/hblock/deny.list

(default: builtin)

🦋 the formatting options

  • -R, --redirection <REDIRECTION>, ${HBLOCK_REDIRECTION} — the redirection used for all entries in the blocklist. (default: 0.0.0.0)
  • -W, --wrap <NUMBER>, ${HBLOCK_WRAP} — breaks blocklist lines after this number of entries, so your file doesn't turn into one unreadable mega-line 😭 (default: 1)
  • -T, --template <TEMPLATE>, ${HBLOCK_TEMPLATE} — the template applied to each entry. the placeholders are literally these:
    • %D = <DOMAIN>
    • %R = <REDIRECTION>

(default: %R %D)

  • -C, --comment <COMMENT>, ${HBLOCK_COMMENT} — the character used for comments. (default: #)

🧚 the behaviour options

  • -l, --[no-]lenient, ${HBLOCK_LENIENT} — match all entries from sources regardless of their IP, instead of only 0.0.0.0, 127.0.0.1, ::, ::1 or nothing. (default: false)
  • -r, --[no-]regex, ${HBLOCK_REGEX} — use POSIX BREs in the allowlist instead of fixed strings. regex girlies rise 🫶 (default: false)
  • -f, --[no-]filter-subdomains, ${HBLOCK_FILTER_SUBDOMAINS} — do not include subdomains when the parent domain is also blocked. super useful for reducing the blocklist size in cases such as when DNS blocking makes these subdomains redundant ✨ (default: false)
  • -n, --retry <NUMBER>, ${HBLOCK_RETRY} — number of times to retry a failed download. bestie said "try again" and meant it 💅 (default: 0)
  • -c, --[no-]continue, ${HBLOCK_CONTINUE} — do not abort if a download error occurs. she pushes through 😤 (default: false)
  • -p, --parallel, ${HBLOCK_PARALLEL} — maximum concurrency for parallel downloads. (default: 4)
  • -q, --[no-]quiet, ${HBLOCK_QUIET} — suppress non-error messages. we love a low-key queen 🤫 (default: false)
  • -x, --color <auto|true|false>, ${HBLOCK_COLOR} — colorize the output. (default: auto)
  • -v, --version — show version number and quit. bye 👋
  • -h, --help — show this help and quit. hi 👋

💀 REPORTING BUGS 💀

found a bug? don't be shy, tell on it:

some credits, because we respect the devs around here 👑:

ngl if something is acting up, the issues page is the move — that's the whole point of it, bestie 🫶

okay that's the page!! mwah 💋 this is hBlock version 3.5.1, dated March 2025, written by that legend Héctor Molinero Fernández — go block some ads, you absolute icon 🌈⭐

📦 where this page comes from