How to install Polipo depends on what your system offers. Some Linux distributions have shipped a ready-made package, while others no longer include it, in which case building from the source repository is the dependable route. This guide covers both paths and finishes with a quick check that the proxy is answering.
The project is archived and no longer maintained, so treat any installation as legacy software. Install it on a machine you control, keep it bound to trusted clients, and read our safety notes before exposing it to a wider network.
Before You Start
A few basics make the process smoother. You need a Unix-like system, a user account with administrator rights for system-wide installation, and a terminal. For a source build you also need a C compiler and the standard build tools.
- A Unix-like operating system such as a Linux distribution or a BSD.
- Administrator access through
sudoor a root shell. - For source builds:
git, a C compiler such as GCC, andmake. - Optional:
texinfoif you want to build the manual.
Installing From a Package Manager
Check your distribution's repository first. On Debian-based systems the package has historically been named polipo, so a search and install look like the example below. If the search returns nothing, your release has likely dropped it and the source build is the next step.
apt search polipo
sudo apt install polipoDistribution packages usually add a system configuration file, a cache directory and a service definition. That saves manual work, but the exact file locations and service names vary, so read the package's documentation afterwards.
Checking what the package installed
After installation, list the package's files to see where the configuration and cache live. On Debian-based systems dpkg -L polipo shows every installed path, which is useful when you start editing settings.
Building From Source
The source code lives in the GitHub repository linked from the download section. Clone it, enter the folder and run the build. The repository includes an INSTALL file with the author's notes, which is worth reading before you continue.
git clone https://github.com/jech/polipo.git
cd polipo
make all
sudo make installBy default the install step places the binary and supporting files under a standard prefix. If you prefer a different location, the Makefile defines variables you can override; check the INSTALL file for the exact names before changing them.
If the build fails
Most build problems come from missing tools. An error about the compiler means GCC or Clang is absent, and an error mentioning makeinfo means texinfo is missing for the manual. Installing those packages and running make again normally resolves it.
Creating a Minimal Configuration
The proxy runs with built-in defaults, but a small configuration file makes your intentions clear. A system-wide file is commonly read from /etc/polipo/config, and a per-user file from ~/.polipo. The minimal example below listens only on the local machine.
proxyAddress = "127.0.0.1"
proxyPort = 8123
diskCacheRoot = "/var/cache/polipo/"Make sure the cache directory exists and is writable by the user that runs the proxy. A missing or read-only cache directory is a common reason for caching silently not working. The configuration guide explains every option shown here.
Starting and Testing the Proxy
If your package installed a service, start it with your system's service manager. For a source build you can launch the binary directly and point it at your configuration file with the -c option. Running it in the foreground first lets you see messages immediately.
polipo -c /etc/polipo/configNext, send a request through the proxy. Using curl with the proxy option is a quick test, and the built-in local interface at the proxy address under /polipo/ confirms that it is listening.
curl -x http://127.0.0.1:8123 -I http://example.com/| Check | Command or location | Expected result |
|---|---|---|
| Proxy responds | curl -x http://127.0.0.1:8123 -I http://example.com/ | HTTP headers are printed |
| Local interface | http://127.0.0.1:8123/polipo/ | Status page loads in a browser |
| Port is listening | ss -ltnp | Port 8123 appears in the list |
Pointing Applications at the Proxy
Once the proxy works, configure your applications to use it. Browsers have manual proxy settings where you enter the address and port, and many command-line tools respect the http_proxy environment variable. Only plain HTTP benefits from caching, since HTTPS is tunnelled.
export http_proxy=http://127.0.0.1:8123What to Do After Installing
With the proxy running, decide which clients may use it, how large the cache should grow and whether you need a parent proxy. Those choices are covered in the guides on cache management and SOCKS parent proxies.
Running It as a Background Service
For everyday use you will want the proxy to start automatically. Packaged installs usually include a service unit or init script, so enabling it with your service manager is enough. On systemd-based distributions, the commands typically follow the pattern below, though the unit name depends on the package.
sudo systemctl enable --now polipo
systemctl status polipoFor a source build, you can write a small service file that runs the binary with your configuration and a dedicated user. Setting daemonise and pidFile in the configuration is an alternative when you prefer a traditional background process.
Using a dedicated user account
Running the proxy as root is unnecessary because the default port is above 1024. Create an unprivileged system user, give it ownership of the cache directory and log file, and start the proxy as that user. This limits the impact of any bug in an archived codebase.
Updating or Removing the Software
Because the project is archived, there are no new official releases to update to. A package install is removed with your package manager, and a source install can usually be cleaned up by deleting the installed binary, manual pages and info files from the install prefix, along with the configuration and cache directories.
- Package installs: remove with your package manager, optionally purging configuration.
- Source installs: delete the installed files under the chosen prefix.
- Both: remove the cache directory if you no longer need stored objects.
Conclusion
How to install Polipo comes down to two options: use your distribution's package if it still exists, or clone the repository and build it with make. Either way, a short configuration that binds to localhost and a writable cache directory give you a working proxy on port 8123.
Test it with curl, then point your applications at it. If something does not behave as expected, the troubleshooting guide covers the most common problems step by step.
