Polipo is a small caching web proxy written in C by Juliusz Chroboczek. It sits between your applications and the web, receives HTTP requests on their behalf, keeps copies of responses on disk and serves those copies again when the same resource is requested. Its design goal was simple: use very modest resources while making web access feel quicker on slow or shared connections.
This guide explains what the software actually does, how its cache works, where it fits today and what you should know before running it. If you only need setup steps, jump to the installation guide after reading the overview below.
Polipo in One Paragraph
A web proxy is a program that forwards requests from clients, such as a browser or a command-line tool, to web servers and passes the answers back. A caching proxy adds memory to that job. When a page, image or file comes back, it can be stored, so the next request for the same object may be answered locally instead of travelling across the network again.
Polipo does this with a single-threaded, non-blocking architecture. Instead of starting a new process or thread for every connection, one event loop handles many connections at once. That approach keeps memory use low and is one reason the program became popular on small home servers, older laptops and embedded boards.
Core Ideas Behind the Design
The project focused on doing a few things well rather than offering every enterprise proxy feature. The points below summarise the behaviour that defines it.
- Disk cache: responses can be written to a cache directory and reused later.
- HTTP/1.1 awareness: it understands persistent connections and can pipeline requests to servers that handle them.
- Partial objects: it can keep part of a resource and complete it later using range requests.
- Parent proxies: it can forward traffic through another HTTP proxy or a SOCKS proxy.
- Local interface: a small built-in web page lets you view status and settings.
Why single-threaded matters
Many proxies scale by spreading work across processes. That is excellent for large organisations but wasteful on a single household connection. Polipo instead waits on sockets efficiently and reacts when data is ready, which lets one modest machine serve several clients comfortably.
How the Cache Works in Practice
When a client asks for a URL, the proxy first checks whether it already holds a fresh copy. If it does, the response is returned immediately, which is called a cache hit. If the copy is missing or stale, the request goes to the origin server, which is a cache miss, and the new response is stored for next time when HTTP caching headers permit it.
Freshness is not guessed blindly. The proxy reads standard headers such as expiry and validation information, and it can revalidate an object with the server instead of downloading it again. You can read more about tuning this behaviour in the cache management guide.
| Situation | What happens | Result for the user |
|---|---|---|
| Fresh copy in cache | Served locally | Faster response, no extra download |
| Stale copy in cache | Revalidated with the server | Small check instead of a full transfer |
| Nothing cached | Fetched from the origin server | Normal speed, then stored if allowed |
| Encrypted HTTPS traffic | Tunnelled with CONNECT | Passed through, not cached |
What It Cannot Cache
Most of today's web runs over HTTPS. A classic caching proxy like this one cannot read encrypted traffic, so HTTPS requests are simply tunnelled through to the destination. That means the caching benefit applies mainly to plain HTTP resources, such as local mirrors, package repositories served over HTTP or internal services.
This limitation is important when you decide whether the software still makes sense for you. On a modern browsing workload the hit rate will usually be much lower than it was when the project was active, because so little browsing traffic is unencrypted.
Who It Suits Today
The proxy remains interesting for learning, for experiments and for specific HTTP workloads. People studying how caching proxies behave often appreciate how small and readable the source code is compared with larger projects.
- Students and hobbyists exploring HTTP caching and proxy behaviour.
- Lab environments that repeatedly fetch the same plain HTTP resources.
- Older or low-power hardware where memory is scarce.
- Setups that need a simple HTTP front end for a SOCKS proxy, covered in the SOCKS and Tor guide.
Project Status You Should Know
The official repository on GitHub is archived, and its README states that the project is no longer maintained. No new fixes are expected from the original author. Anyone using it on a network should treat it as legacy software, keep it bound to trusted clients and watch for issues in their distribution.
This does not erase its usefulness for study or limited private use, but it does change the risk picture. Our article on whether it is still safe to use walks through sensible precautions and alternatives.
License and Source Code
The code is released under the MIT license, which allows use, modification and redistribution with the license notice kept intact. The full source, including installation notes and a texinfo manual, is available from the repository linked in the download section.
Because it is plain C with few dependencies, building it on a Unix-like system is usually straightforward. Distribution packages may also exist, though some repositories have dropped the package since the project was archived.
Where the Name Comes From
The word polipo is Italian, commonly translated as octopus or polyp. The software shares the name, but searches for the word often mix technical and everyday meanings. If you came here for the language side, see the Polipo meaning guide, which covers Italian, Spanish and English usage.
Conclusion
Polipo is a compact, single-threaded caching web proxy that stores HTTP responses on disk, revalidates them intelligently and can forward traffic through parent proxies. It was built to stay light on resources, and that design still makes it a neat piece of software to study and run on small systems.
Its archived status and the dominance of HTTPS limit its role on today's networks, so use it with care, keep access restricted and consider maintained alternatives for production work. When you are ready to try it, start with the installation steps.
