If upgrading, from versions before 2.9.16, please back up any configuration
files. See the Note to Upgraders Section.
Install Privoxy. See the Installation Section below for platform specific
Advanced users and those who want to offer Privoxy
service to more than just their local machine should check the main config file, especially the security-relevant options. These are
off by default.
Start Privoxy, if the installation program has
not done this already (may vary according to platform). See the section
Set your browser to use Privoxy as HTTP and
HTTPS proxy by setting the proxy configuration for address of
127.0.0.1 and port 8118.
(Junkbuster and earlier versions of
Privoxy used port 8000.) See the section Starting Privoxy below
for more details on this.
Flush your browser's disk and memory caches, to remove any cached ad images.
A default installation should provide a reasonable starting point for
most. There will undoubtedly be occasions where you will want to adjust the
configuration, but that can be dealt with as the need arises. Little
to no initial configuration is required in most cases.
See the Configuration section for more
configuration options, and how to customize your installation.
If you experience ads that slipped through, innocent images that are
blocked, or otherwise feel the need to fine-tune
Privoxy's behaviour, take a look at the actions files. As a quick start, you might
find the richly commented examples
helpful. You can also view and edit the actions files through the web-based user interface. The
Appendix "Anatomy of an
Action" has hints how to debug actions that
Please see the section Contacting the
Developers on how to report bugs or problems with websites or to get
Now enjoy surfing with enhanced comfort and privacy!
Ad blocking is but one of Privoxy's
array of features. Many of these features are for the technically minded advanced
user. But, ad and banner blocking is surely common ground for everybody.
This section will provide a quick summary of ad blocking so
you can get up to speed quickly without having to read the more extensive
information provided below, though this is highly recommended.
First a bit of a warning ... blocking ads is much like blocking SPAM: the
more aggressive you are about it, the more likely you are to block
things that were not intended. So there is a trade off here. If you want
extreme ad free browsing, be prepared to deal with more
"problem" sites, and to spend more time adjusting the
configuration to solve these unintended consequences. In short, there is
not an easy way to eliminate all ads. Either take
the easy way and settle for most ads blocked with the
default configuration, or jump in and tweak it for your personal surfing
habits and preferences.
Secondly, a brief explanation of Privoxy's
"actions". "Actions" in this context, are
the directives we use to tell Privoxy to perform
some task relating to HTTP transactions (i.e. web browsing). We tell
Privoxy to take some "action". Each
action has a unique name and function. While there are many potential
actions in Privoxy's
arsenal, only a few are used for ad blocking. Actions, and action
configuration files, are explained in depth below.
Actions are specified in Privoxy's configuration,
followed by one or more URLs to which the action should apply. URLs
can actually be URL type patterns that use
wildcards so they can apply potentially to a range of similar URLs. The
actions, together with the URL patterns are called a section.
When you connect to a website, the full URL will either match one or more
of the sections as defined in Privoxy's configuration,
or not. If so, then Privoxy will perform the
respective actions. If not, then nothing special happens. Furthermore, web
pages may contain embedded, secondary URLs that your web browser will
use to load additional components of the page, as it parses the
original page's HTML content. An ad image for instance, is just an URL
embedded in the page somewhere. The image itself may be on the same server,
or a server somewhere else on the Internet. Complex web pages will have many
such embedded URLs.
The actions we need to know about for ad blocking are: block, handle-as-image, and
block - this action stops
any contact between your browser and any URL patterns that match this
action's configuration. It can be used for blocking ads, but also anything
that is determined to be unwanted. By itself, it simply stops any
communication with the remote server and sends Privoxy's
own built-in BLOCKED page instead to let you now what has happened.
tells Privoxy to treat this URL as an image.
Privoxy's default configuration already does this
for all common image types (e.g. GIF), but there are many situations where this
is not so easy to determine. So we'll force it in these cases. This is particularly
important for ad blocking, since only if we know that it's an image of
some kind, can we replace it with an image of our choosing, instead of the
Privoxy BLOCKED page (which would only result in
a "broken image" icon). There are some limitations to this
though. For instance, you can't just brute-force an image substitution for
an entire HTML page in most situations.
set-image-blocker - tells
Privoxy what to display in place of an ad image that
has hit a block rule. For this to come into play, the URL must match a
block action somewhere in the
configuration, and, it must also match an
The configuration options on what to display instead of the ad are:
| pattern - a checkerboard pattern, so that an ad
replacement is obvious. This is the default.
| blank - A very small empty GIF image is displayed.
This is the so-called "invisible" configuration option.
| http://<URL> - A redirect to any image anywhere
of the user's choosing (advanced usage).
The quickest way to adjust any of these settings is with your browser through
the special Privoxy editor at http://config.privoxy.org/show-status
(shortcut: http://p.p/show-status). This
is an internal page, and does not require Internet access. Select the
appropriate "actions" file, and click
"Edit". It is best to put personal or
local preferences in user.action since this is not
meant to be overwritten during upgrades, and will over-ride the settings in
other files. Here you can insert new "actions", and URLs for ad
blocking or other purposes, and make other adjustments to the configuration.
Privoxy will detect these changes automatically.
A quick and simple step by step example:
Right click on the ad image to be blocked, then select
"" from the
Set your browser to
Find user.action in the top section, and click
You should have a section with only
block listed under
If not, click a "Insert new section below"
button, and in the new section that just appeared, click the
Edit button right under the word "Actions:".
This will bring up a list of all actions. Find
block near the top, and click
in the "Enabled" column, then "Submit"
just below the list.
Now, in the block actions section,
click the "Add" button, and paste the URL the
browser got from "".
Remove the http:// at the beginning of the URL. Then, click
"OK" if in a pop-up window).
Now go back to the original page, and press SHIFT-Reload
(or flush all browser caches). The image should be gone now.
This is a very crude and simple example. There might be good reasons to use a
wildcard pattern match to include potentially similar images from the same
site. For a more extensive explanation of "patterns", and
the entire actions concept, see the Actions
For advanced users who want to hand edit their config files, you might want
to now go to the Actions Files Tutorial.
The ideas explained therein also apply to the web-based editor.