YaCy

Last reviewed Sep 13, 2026 · 818 words

Do not install YaCy hoping to replace Google. The peer-to-peer "freeworld" network has been running since 2003 and its results for an ordinary query are still poor: sparse coverage, weak ranking, a lot of dead links. Install it instead as a private crawler for a defined set of sites, a documentation portal, a company intranet, your own bookmarks, and it becomes a useful tool that costs 1 GB of RAM and a Java runtime. The distinction is the whole guide.

Two modes, and the one people expect is the weak one

YaCy runs in one of two network modes. In freeworld mode your instance joins the public peer network: it crawls, shares its index shards with other peers, and answers queries by fanning them out across the network. This is the headline feature, censorship-resistant search with no central authority, and it is also the mode where quality disappoints, because ranking across a few hundred volunteer peers with uneven crawls cannot compete with an index built by a company with 100,000 servers.

In Robinson mode the instance stands alone. It crawls what you tell it, indexes locally, and answers only from its own data. This is where I have seen YaCy earn its keep: a support team searching 40,000 pages of internal wiki and vendor docs, a university indexing its own departmental sites, a home-labber wanting full-text search across every article they have ever saved. Pick the mode on the basic configuration page on first run and do not join the network unless you specifically want to contribute crawl capacity.

Java sizing is the first thing to get right

The Docker image is yacy/yacy_search_server, the web UI lives on port 8090, and out of the box the JVM heap is small enough that an index of a few hundred thousand documents will start throwing memory warnings. Set the heap explicitly before crawling anything serious; the setting is under Performance in the admin UI and persists in DATA/SETTINGS/yacy.conf. My working rule: 1 GB heap for a personal index under 100,000 documents, 2 to 4 GB for anything a team depends on, and give the container at least 1 GB above the heap. A minimal compose file:

services:
  yacy:
    image: yacy/yacy_search_server:latest
    ports:
      - "8090:8090"
    volumes:
      - ./yacy-data:/opt/yacy_search_server/DATA
    restart: unless-stopped

Set an admin password immediately under Administration; a fresh install leaves admin pages reachable from localhost without one, which is fine on a laptop and not fine on a server. Disk grows roughly with pages crawled; budget 10 to 20 GB for a mid-sized private index and watch it.

Crawling is the part with sharp edges

The Advanced Crawler page controls depth, domain restriction, and whether to obey robots.txt (leave that on). A crawl with depth 3 and no domain limit will happily wander across the internet for days; restrict it to the start domain and set a maximum page count. Crawls are re-runnable on a schedule, which is how you keep an intranet index fresh. Expect the crawler to be the thing that pegs CPU: a single-core VM will feel it, and Java's memory behaviour means a crawl that runs out of heap tends to slow to a crawl rather than fail cleanly.

Search quality on a private index is good; on the public net it is not

Once the crawl is done, the local search is solid: full-text over the embedded Solr, filters by domain, file type, language and date, plus an OpenSearch-compatible API and RSS results so you can wire it into a browser search bar or a script. For "find that page I know exists" over content you chose, it beats grepping through a bookmarks export. For general web queries, the honest answer is a metasearch engine. SearXNG queries Google, Bing, DuckDuckGo and dozens of others on your behalf, strips the tracking, and returns results in about a second on 512 MB of RAM. It is the bigger project, the more common self-hosted choice, and the right answer for the Google Search replacement use case that people usually have in mind. The two are not rivals: SearXNG can add a YaCy instance as one of its engines.

What I'd do

Run YaCy in Robinson mode as a private index for a bounded set of sites, with a 2 GB heap, an admin password set on day one, and a scheduled recrawl. Put SearXNG next to it for everything else and add the YaCy instance as an engine so both appear in one search box. Skip the freeworld network unless contributing to a decentralised index matters to you as a cause, which is a fine reason but is not the same as getting good results. Other options in the category are listed under search.