Welcome to TBlock documentation!

This is the place where you can learn how to use TBlock and how it works. If this is your first time using TBlock, we recommend you to read this documentation from the beginning, but you can also select the chapter you are interested into.

Please note that this documentation is available only for TBlock version 2.2.0 or later. The information written here may not be compatible with previous versions.

Chapters summary

  1. Introduction
  2. Filter lists
  3. User rules
  4. Getting information
  5. More operations
  6. Daemon
  7. Filter list converter
  8. Configuration
  9. Troubleshooting
  10. FAQ
  11. License

In this chapter

  1. Terminology
  2. How it works


IP address

An IP address is a suite of numbers from 0 to 255, seperated by dots (for instance Every time you connect to the internet, you ISP (Internet Service Provider) assigns you a public IP address. This address is unique, and it can be used to access content on the device that has this address. In that case, the device is called a server.


DNS stands for Domain Name System. It is a service that is used by computers to connect to websites. When a computer tries to connect to, it sends a request to a DNS server, which sends a response containing the IP address of The connection from the computer to is now possible.

Hosts file

The hosts file is a file that is present on all operating systems. It acts like a DNS, but has a higher priority than the DNS. It can be used to redirect hosts (such as to custom IP addresses.


As the name suggests, a database is simply an efficient way to store data.

Filter list

A filter list is a text file, containing a list of domains (for instance, that can be used by an ad-blocker to block all domains that are on it. Depending on the format, it is possible to also whitelist some domains inside a filter list. Whithout filter lists, ad blocking wouldn't be possible.


A rule is a way to tell an ad-blocker what to do about a specific domain. In fact, a filter list is a set of rules, that tells the ad-blocker which domains to block and which not to block.

Filter list format / syntax

The format (or syntax) of a filter list is simply a way to write rules inside the list so that the ad-blocker understands what to do with the specified hosts. Different ad-blockers use different formats. For instance, Adblock Plus uses an advanced syntax that allows to block hosts under certain conditions. This is not possible with others, such as AdAway or pi-hole, or TBlock. However, TBlock supports the most popular filter lists. It means the users should not have to worry about that.


A policy is the instruction a rule gives to the ad-blocker about a specific host. A policy can either be ALLOW, BLOCK or REDIRECT. If the policy is ALLOW, then the host is whitelisted. If the policy is BLOCK, the host is blocked, and if it is REDIRECT, the domain is redirected to the ip address specified in the rule.


In computing, a daemon is a program that runs in the background, performing invisible but yet important tasks for the daily user. Without daemons, it wouldn't be possible to have a graphical desktop.

How it works

Filter list repository

As we already said, filter lists are essential for an efficient protection against advertising and tracking. However, finding these filter lists may be difficult for a new user. That's why TBlock has an official filter list repository, allowing the user to use them just with one simple operation. Almost all filter lists available on the repository are also mirrored by the team behind TBlock, to improve decentralization in case a server is down.

Hosts file and localhost

To block domains, TBlock uses the hosts file. With it, it redirects all blocked domains to the local IP address, That way, when a program or a web page tries to connect to a blocked domain, it connects to the local address instead. It means that the requested tracking script or advert is not available and thus not loaded.

Filter lists

In this chapter

  1. Types of filter lists and permissions
  2. Syncing the filter list repository
  3. Subscribing and updating filter lists
  4. Adding custom filter lists
  5. Unsubscribing from filter lists
  6. Managing filter lists

Types of filter lists and permissions

Official filter lists

Official filter lists are filter lists that can be found on the filter list repository. Some details (such as syntax, license and homepage) about them are also provided.

Custom filter lists

A custom filter list is a filter list that is not available on the repository, that the user had to add manually.


Permissions are a way to control which rule policies a specific filter list is allowed to use. By default, filter lists are only allowed to set blocking rules.

Syncing the filter list repository

Initial sync

The filter list repository is what makes TBlock unique. With a simple command, users can subscribe to the most popular and powerful lists available. Before being able to subscribe to these official filter lists, however, it is important to sync the repository, so that TBlock knows what these lists are and where to download them. To do so, you only have to run this as root (or with administration permissions):

tblock -Y

You may also use the long operation:

tblock --sync

Since new filter lists are regularly added to the repository, it is important to keep it up-to-date, by syncing the repository as frequently as possible.

Note: the daemon allows you to automate the process of syncing the repository.


By default, if your local version of the repository is up-to-date, nothing will be done. However, you may want to force-sync, to sync it even if it is up-to-date. To do so, simply run:

tblock -Yf

Or the long operation:

tblock --sync --force

Subscribing and updating filter lists


To subscribe to a filter list (in this case easylist), simply run:

tblock -S easylist

You may use the long operation as well:

tblock --subscribe easylist

Subscribe to many filter lists

Of course, you can subscribe as many filter lists as you want at the same time, by appending them at the end of the command (also works with long operation):

tblock -S easylist easyprivacy tblock-base

Subscribe and sync

Since it is recommended to sync the filter list repository as frequently as possible, you may want to sync the repository while subscribing to filter lists in only one operation:

tblock -Sy easylist

Or the long operation:

tblock --subscribe --with-sync easylist


Once you've subscribed to the filter lists you want to, it is important to keep them up-to-date as well (for instance if a list contains a false-positive host). To do so, simply run:

tblock -U

Or the long operation:

tblock --update

Sync and update

Since it is important to keep both repository and filter lists up-to-date, you may want to sync/update them at the same time:

tblock -Uy

And the long operation:

tblock --update --with-sync

Sync, update and then subscribe

You can also sync the repository, update all filter lists and then subscribe to new lists with a single operation:

tblock -Syu easyprivacy

Or the long version (really long this time):

tblock --subscribe --with-sync --with-update easyprivacy

Cleaning the cache

When TBlock fetches a filter lists, it automatically stores it in cache. However, you may want to delete cached filter lists to free up some space on your device. To do so, run:

tblock -P


tblock --purge-cache

Adding custom filter lists

Adding a custom filter list

To add a custom filter list, you have to give it a name that doesn't already exist on the repository. You also need to specify the link/local path of the plain text filter list. To do so:

tblock -C example-org ''

You can also use the long operation:

tblock --add-custom example-org ''

Adding many filter lists

You can also subscribe to many custom filter lists at the same time, by appending them at the end of the command (always the name first, and then the link/path of the list):

tblock -C \
    example-org '' \
    local-list '/home/user/blocklist.txt'

Specifying the syntax of a custom filter list

Thanks to TBlock's advanced technology, you usually shouldn't have to worry about the syntax of the custom filter list you are adding. However, with huge lists, you can save some time by specifying manually the syntax (in this example hosts):

tblock -C example-org '' -x hosts

There is also a long operation available:

tblock --add-custom example-org '' --custom-syntax hosts

Note: if you specify the syntax, TBlock will use it for all the custom filter lists that are given in the same command. It means that you can't use this option if you are trying to add two lists that have different formats.

Renaming a custom filter list

You can rename custom filter lists by running:

tblock -N id1-old id1-new id2-old id2-new


tblock --rename id1-old id1-new id2-old id2-new

Unsubscribing from filter lists


If you don't want to subscribe to a filter list anymore, you can easily remove it (in this case easylist):

tblock -R easylist

You may want to use the long operation:

tblock --remove easylist

Note: just as subscribing, you can remove several filter lists at the same time by passing them after the --remove operation.

Unsubscribe and update

Once a filter list is removed, so are its rules. However, if another filter list blocks the same domains than the removed list, you need to update your lists for the rules to be restored. You can do so by running:

tblock -Ru easylist

Or the long operation:

tblock --remove --with-update easylist

Managing filter lists permissions

Change the permissions

By default, filter lists are only allowed to define blocking rules. However, you can grant them the permission to define allowing or redirecting rules.

To grant a filter list allowing and blocking permissions (in this example easylist):

tblock -M easylist -p AB

Or the long operation:

tblock --mod easylist --permissions AB

Note: the letter A stands for Allowing rules, B for Blocking rules, and R for Redirecting rules.

To grant a filter list allowing and redirecting permission only:

tblock -M easylist -p AR

Note: redirecting rules can compromise your network traffic and lead to MITM attacks. Be sure to fully trust the filter lists you grant the "redirecting" permission.

To restore the default permissions (blocking only):

tblock -M easylist -p B

User rules

In this chapter

  1. What user rules are
  2. Defining user rules
  3. Deleting user rules

What user rules are

User rules are rules that are set directly by the user. They have a greater priority than regular rules, which means they overwrite rules that are set by filter lists. They can be useful for allowing domains that are blocked without having to remove a whole filter list.

Exactly like regular rules, they can have three different policies: ALLOW, BLOCK and REDIRECT.

Defining user rules

Allowing a domain

To allow domains (prevent it from being blocked/redirected by filter lists), run:

tblock -a

Or the long operation:

tblock --allow

Allow wildcards

With TBlock, you can also add wildcards allowing rules. Here, to allow all subdomains of but not itself:

tblock -a *

Blocking a domain

To block domains, run:

tblock -b

Or the long operation:

tblock --block

Redirecting a domain

Redirecting domains should not be done, unless you know exactly what you are doing. If so, then you can redirect the domains you want to a specific IP address (in this case

tblock -r -i

Or the long operation:

tblock --redirect --ip

Deleting user rules

Deleting a set of rules

To delete existing user rules, use the operation:

tblock -d

Or its long alternative:

tblock --delete-rule

Getting information

In this chapter

  1. Listing rules
  2. Querying domains
  3. Listing filter lists
  4. Browsing filter lists

Listing rules

Listing rules

Sometimes, it can be useful to know whether a domain is blocked, allowed, redirected, or if the rule doesn't exist. You may also want to know which rules a specific filter list contains. You can list all rules present in TBlock's database:

tblock -l

Or the long operation:

tblock --list-rules

Listing user rules only

It is important to see which rules are user rules and which ones aren't, because user rules have a higher priority than other rules. To list all user rules:

tblock -le

The long version:

tblock --list-rules --user

Listing non-user rules only

You can also list all rules that are set by filter lists, but exclude user rules from them:

tblock -lt


tblock --list-rules --standard

Listing rules from specific filter lists only

You can also list the rules from a specific filter list only (or several). Here we'll assume that you want to list the rules from easylist and easyprivacy:

tblock -lm easylist easyprivacy

With the long version:

tblock --list-rules --from-filters easylist easyprivacy

Querying domains

Listing user rules is useful, but what if we want to simply check if a rule exists?

A solution would be to run:

tblock -l | grep ""

However, with this solution, we can't see which filter list owns the rule. But it's alright, because TBlock 2.2.0 introduced a new option for this purpose!

Simply run:

tblock -W


tblock --which

Listing filter lists

Just as you can list rules, you can also list filter lists.

Listing all filter lists

When you list filter lists, all filter lists are shown by default (both the ones available on the repository and the ones you added manually):

tblock -L


tblock --list

Listing custom filter lists only

To list only the filter lists that have been manually added by the user, run:

tblock -Lc

Or the long version:

tblock --list --custom

Listing only non-custom filter lists

To list only filter lists that are in the repository index:

tblock -Lw

Or, with the long operation:

tblock --list --on-repo

Listing only subscribed filter lists

You can also list only the filter lists you are subscribing to:

tblock -Lk


tblock --list --subscribing

Listing only not-subscribed filter lists

You can also list only the filter lists you are not subscribing to:

tblock -Lz


tblock --list --not-subscribing

Listing non-custom and subscribed filter lists

The options can be combined together. For instance, to list all filter lists that are both available in the repository index and subscribed:

tblock -Lwk


tblock --list --on-repo --subscribing

Listing non-custom and not-subcribed filter lists

To list only filter lists that are both available in the repository index and not subscribed:

tblock -Lwz


tblock --list --on-repo --not-subscribing

Browsing filter lists


You can search a specific word or tag accross filter lists, just as you would do with a search engine.

To search for filter lists that block tracking, for instance, we would run:

tblock -Q "tracking"


tblock --search "tracking"

Filtering search results

Just as with the listing operation, the four options --custom, --on-repo, --subscribing and --not-subscribing can be added to the search operation to filter the results.

For instance, if we wanted to search for blocklists that block ads and that we are not subscribing to, we would run:

tblock -Qz "ads"


tblock --search --not-subscribing "ads"

If we want to search for filter lists that include easylist, that are available in the repository index and that we are subscribing to, we need to run:

tblock -Qwk "easylist"
tblock --search --on-repo --subscribing "easylist"

Getting information about a specific filter list

We can also display information about a specific filter list (such as name, whether we are subscribing to it, tags, source, license, rules count, etc.). Assuming we want to get information about easylist, we have to run:

tblock -I easylist


tblock --info easylist

More operations

In this chapter

  1. Toggling protection
  2. Getting status information
  3. Show help and version information

Toggling protection

Refreshing rules

If your hosts file was modified, you may want TBlock to refresh its rules (update the hosts file without updating your filter lists). To do so:

tblock -H

The long operation:

tblock --update-hosts

Disabling protection

To disable the protection and restore your default hosts file, run:

tblock -D

With the long operation:

tblock --disable

Enabling protection

If you disabled TBlock, it is easy to enable its protection again:

tblock -E


tblock --enable

Getting status information

If we want to see if TBlock is active or not, the total rules count, or the number of active filter lists, we can do so by running:

tblock -s

Or the long operation:

tblock --status

Show help and version information

Showing help page

Like all command-line tools, it is possible to display a help page for TBlock:

tblock -h


tblock --help

Showing version and license information

To show current version and licensing information, run:

tblock -v


tblock --version


In this chapter

  1. Daemon quick overview
  2. Starting the daemon

Daemon quick overview

History & use

The daemon was introduced in TBlock version 2.0.0. It is a simple utility that runs in background and that can perform the following tasks:

  • Update the filter lists (and sync the repository index) at a regular time interval
  • Protect the hosts file against being edited by another program or user

Multiple instances

By default, only one instance of the daemon can run at the same time. When an instance of the daemon starts, it creates a PID file, and, if the file already exists then it fails to start. The PID file is removed when the instance of the running daemon stops.

Starting the daemon

Starting a single instance

To start an instance of the daemon, simply run (assuming your configuration is located under /etc/tblock.conf):

tblockd -dc /etc/tblock.conf

Or the long alternative:

tblockd --daemon --config=/etc/tblock.conf

Starting another instance

If an instance of the daemon is already running, you are not able to start another instance by default. However, you can do that by telling the new instance to ignore the PID file:

tblockd -dnc /etc/tblock.conf

Or with the long version:

tblockd --daemon --no-pid --config=/etc/tblock.conf

Filter list converter

In this chapter

  1. Introduction to the converter
  2. Working with syntax
  3. Using the converter

Introduction to the converter

The converter is yet another great feature provided by TBlock. It allows users to easily convert filter lists from a syntax to another one. This can be useful for distributing home-made lists, while assuring their compatiblity with different ad-blockers.

Working with syntax

Listing available formats

To list available filter list formats/syntax, run:

tblockc -l


tblockc --list-syntax

Get the format of a file

To detect the format/syntax of a filter list, run (assuming the file you want to check is list.txt):

tblockc -g list.txt

Or the long operation:

tblockc --get-syntax list.txt

Using the converter

Convert a filter list

The converter allows you to convert a filter list into another format. Here, we'll convert filter.txt into the hosts format, and write the output to output.txt:

tblockc -C filter.txt -s hosts -o output.txt


tblockc --convert filter.txt --syntax hosts --output output.txt

Convert and specify the input format

By default, the converter detects the format of the input list. However, since this operation can be slow with huge blocklist, you can specify it manually. Here, the format of the filter.txt is adblockplus:

tblockc -C filter.txt -i adblockplus -s hosts -o output.txt


tblockc --convert filter.txt --input-syntax adblockplus --syntax hosts --output output.txt

Keep comments

By default, the converter only converts compatible rules. However, you can choose to also convert comments:

tblockc -Cc filter.txt -s hosts -o output.txt


tblockc --convert --comments filter.txt --syntax hosts --output output.txt


In this chapter

  1. General configuration
  2. Daemon configuration

General configuration

TBlock's configuration file is located under /etc/tblock.conf on GNU/Linux and under "%ALLUSERSPROFILE%\TBlock\conf.ini on Windows. It can be used to modify TBlock's behavior.

Change default blocking address

By default, TBlock redirects blocked domains to However, if you want to change this value, for instance to, you just need to write this line under the [default] section of your config:


# Let's change the default blocking address
default_ip =

Enable IPv6 blocking

By default, TBlock redirects blocked domains to the local IPv4 address only. If you want to enable redirecting to IPv6, write the following line (still under the [default] section):

# Let's allow IPv6 redirecting rules and IPv6 blocking
allow_ipv6 = false

Note: your hosts file will be twice bigger than before if you enable this setting.

Change default IPv6 blocking address

Just as we can change the default IPv4 blocking address, we can also change the IPv6 one, by writing under the [default] section:

default_ipv6 = ::1

Change default filter lists permissions

By default, filter lists are only allowed to set blocking rules. If you want to change this setting, simply write under the [default] section in your config (here to allow filter lists to set allowing and blocking rules by default):

# Default filter permissions (A for Allow, B for Block, R for Redirect)
# Multiple permissions are supported.
default_permissions =   AB

Note: it is discouraged to set the redirecting permissions by default, since this can possibly lead to security flaws on your device. Only give this permissions to filter lists you fully trust!

Daemon configuration

Syncing the repository index

By default, the daemon updates both the filter lists and the repository index. If you want to change this setting, write:

# Do not sync the repository index when updating filter lists
sync_repo = false

Changing the update frequency

By default, filter lists are updated every 4 hours. You can change this value (for instance to 8 hours) by writing under the [daemon] section of your config:

# Update filter lists every x minutes
frequency = 480

Note: the time specified here is in minutes. For one hour, we will write 60, for two 120, etc.


By default, filter lists are updated normally. If you want to force-update instead, edit the following line under the [daemon] section:

# Force-update filter lists
force = true

Protection against hosts file modification

By default, the daemon prevents other programs or users from editing your hosts file while running. This improves the security of your device, but you may want to disable it. To do so, simply write the following line under the [daemon] section:

anti_hijack = false


Here is a list of the common issues

The daemon does keeps updating every 240 minutes, even though I specified a lower value in the configuration file

This bug is usually caused by the fact that you specified a value that's too low for the daemon in your configuration file. The lowest value supported by the daemon is 60 minutes. If the value you specified is lower than 60 minutes, it will automatically change it to 240 minutes (which is the default value).

tblock module not found

When running TBlock as root, you can possibly get an error message such as:

importlib.metadata.PackageNotFoundError: No package metadata was found for tblock
ModuleNotFoundError: No module named 'tblock'

This is usually caused by the fact that you installed TBlock using pip and its --user option. To solve that, follow the steps below.

First, remove the Python package:

pip uninstall --user tblock

Next, install it again with pipx or any other installation method.

Daemon is unable to start: /usr/bin/tblockd does not exist

Depeding on the installation method you choose, the daemon might not be installed under /usr/bin/tblockd, but rather under /usr/bin/local/bin/tblockd.

To fix that, you simply have to create a symbolic link under /usr/bin/tblockd, pointing to the real executable:

ln -s /usr/local/bin/tblockd /usr/bin/tblockd


Why do I still see ads after installing and setting up TBlock?

Since TBlock uses the hosts file, it gives you a systemwide protection. However, it can't block specific scripts like browser addons do. It means that you may still see some sneaky ads. The only thing you can do is to subscribe to more and to bigger filter lists.

Domains are not blocked

If you use Tor Browser or if your browser uses DNS-over-HTTPS, it will interfere with TBlock. Since TBlock acts like a DNS server, it can't be used if the browser proxies the DNS requests. You'll have to disable your browser's settings, or, in the case of Tor Browser, simply don't care.

Simply because that means that they would by able to redirect any domain to any server they want. This could cause compromise all your network traffic.

For example, a filter list could redirect your mail server to a phishing website, and you wouldn't even notice. This is why it is recommended to allow only trusted filter lists to set redirecting rules.

You can check at any time if there are any redirecting rules set by running:

tblock -l | grep "REDIRECT"

I think I found an issue. What should I do?

It depends. If the issue you found is a vulnerability, than please report it to us via an encrypted email. Otherwise, have a look at this document that contains useful information for reporting issues.

How to backup my filter lists

If you want to make a backup of the filter lists you subscribe to, you can simply run the following:

tblock -Lk > tblock-backup.txt

Then, to restore it:

tblock -Sy $(cat tblock-backup.txt)


This documentation

This documentation is published under the GNU Free Documentation License, Version 1.3:

Copyright (C)  2022 Twann.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the section entitled "GNU
Free Documentation License".


TBlock is released under the GNU General Public License, Version 3.0.


TBlock's website is released under the Creative Commons Attribution-ShareAlike 4.0 International License.