Nexus as a cache: PyPI, npm and Maven proxy repository

Every build that downloads its dependencies straight from PyPI, npm or Maven Central pays twice: in latency and in fragility (a removed package or an unavailable repository breaks the CI). A Nexus proxy repository fixes both: it sits in front of the public repository, caches what passes through, and serves later requests from the local disk. This guide creates a PyPI proxy, plugs pip into it, and proves the pull-through cache. Intended audience: beginner to intermediate. Validated on Nexus 3.96.0-09.

What you will learn

• Understand how a proxy repository works (pull-through cache).
• Create a PyPI, npm or Maven proxy.
• Configure a client to go through Nexus.
• Verify that a package is really cached.

Prerequisites

• A running Nexus instance, see Install Nexus.
• The admin password.

What a proxy repository is

A proxy repository is a lazy mirror of a remote repository. It copies nothing in advance: on the first download of a package, Nexus fetches it upstream, serves it to the client and keeps a copy. Later requests are served from this local cache, without touching the public repository again. This is the pull-through cache.

The benefits are direct: faster builds (the package is already there), resilience (an outage of the upstream repository does not prevent serving what is cached) and control (you see everything your projects consume go through).

Create a proxy repository

Nexus already creates a pypi-public-proxy by default, but let us see how to declare one. In the interface, Administration, Repositories, Create repository, then pypi (proxy). Two fields matter: the name and the remote URL.

Field	Value for PyPI
Name	pypi-public-proxy
Remote storage	https://pypi.org

Swipe to see more

The same mechanism exists for each format: https://registry.npmjs.org for npm, https://repo1.maven.org/maven2/ for Maven Central. You can also create a proxy through the API, handy for scripting an installation:

curl -u admin:VOTRE_MDP -X POST \
  http://localhost:8081/service/rest/v1/repositories/pypi/proxy \
  -H 'Content-Type: application/json' -d '{
    "name": "pypi-public-proxy",
    "online": true,
    "storage": {"blobStoreName": "default", "strictContentTypeValidation": true},
    "proxy": {"remoteUrl": "https://pypi.org", "contentMaxAge": 1440, "metadataMaxAge": 1440},
    "negativeCache": {"enabled": true, "timeToLive": 1440},
    "httpClient": {"blocked": false, "autoBlock": true}
  }'

The repository configuration page shows these same settings in the interface:

The settings that matter

Three options govern the behaviour of the cache:

• Remote storage: the URL of the remote repository to cache (https://pypi.org). It is the only truly mandatory field.
• Maximum component age: the duration (in minutes, 1440 = 24 h) during which Nexus serves an artifact without rechecking upstream. For a releases repository (immutable), you set -1 (never recheck); for snapshots, a short value.
• Auto blocking: if upstream becomes unreachable, Nexus automatically blocks outgoing calls so as not to make clients wait, and restores them when upstream comes back. This is what makes your builds resilient to a PyPI outage.

Plug the client into Nexus

On the client side, you replace the public repository URL with the one of the Nexus proxy. For pip, you point the index at the URL of the Nexus repository:

~/.config/pip/pip.conf

[global]
index-url = http://localhost:8081/repository/pypi-public-proxy/simple/

From now on, pip install <package> goes through Nexus, which caches along the way. For npm, you would do the same with npm config set registry http://localhost:8081/repository/npm-public-proxy/.

Without the EULA accepted, the proxy serves nothing

On a fresh Community Edition instance, a proxy repository answers 200 on its index, shows the list of packages, and returns 403 on every download as long as the EULA is not accepted. The symptom looks like a permissions problem, whereas it is a licence matter: the Sonatype documentation states that downloads and uploads are blocked until an administrator agrees. The first-start wizard has you accept it; for an automated installation, see the API path in Install Nexus.

Prove the pull-through cache

This is the check that counts. You count the cached components, download a package through the proxy, then recount: the package must appear.

1. Count the components before:

   curl -s -u admin:VOTRE_MDP \
     "http://localhost:8081/service/rest/v1/components?repository=pypi-public-proxy" \
     | jq '.items | length'

   6

2. Download a package through the proxy (here the six wheel):

   curl -s -u admin:VOTRE_MDP -o /tmp/six.whl \
     "http://localhost:8081/repository/pypi-public-proxy/packages/six/1.16.0/six-1.16.0-py2.py3-none-any.whl"

   You authenticate, because anonymous access is not enabled by default: without credentials, the index answers 401 and you believe the proxy is down.

3. Recount and verify that six is now cached:

   curl -s -u admin:VOTRE_MDP \
     "http://localhost:8081/service/rest/v1/components?repository=pypi-public-proxy" \
     | jq -r '.items | "nb: \(length)"'

   nb: 7

The counter goes from 6 to 7 and six 1.16.0 now appears in the cache. The second download of the same package will be served without contacting PyPI: the pull-through cache is proven.

The Browse view of the proxy repository lists the packages actually cached, including six which we just downloaded, alongside requests, urllib3 and their dependencies:

Aggregate behind a single URL: the group repository

In practice, you never configure a client directly on a proxy. You create a group repository that brings together the public proxy and a private hosted repository, and the clients point at that group. Nexus then looks first in the private one, then in the proxy, behind a single URL.

Configuring a group boils down to ordering its members. Here, the pypi-all group contains the private hosted repository, then the public proxy:

The order matters: Nexus queries the members from top to bottom and returns the first match. By putting the private hosted first, an internal version masks any public namesake, which protects against a dependency confusion attack. On the client side, you simply point at the group:

~/.config/pip/pip.conf

[global]
index-url = http://localhost:8081/repository/pypi-all/simple/

Clean up automatically: cleanup policies

A cache grows endlessly if you do not prune it, and in the Community Edition it ends up hitting the 40,000-component quota. Cleanup policies automatically delete artifacts according to criteria: not downloaded for X days, older than Y, or beyond a number of versions to keep.

You create a policy under Administration, Cleanup Policies. Here, a rule purges PyPI packages not downloaded for 30 days:

A policy must be assigned to a repository

Creating the policy is not enough: it stays inactive until you assign it to one or more repositories, in the configuration tab of each repository. A scheduled task then applies the rule at the configured frequency. Always start with a wide duration (90 days) and tighten it: a purge that is too aggressive deletes packages that are still useful.

Hands-on practice

The lab has you bring into service a Nexus that is already running: accept the EULA, change the throwaway password, then create the three repositories this guide talks about, the proxy, the hosted and the group that aggregates them. The validation checks the order of the members of the group, not only their presence: Nexus serves the first match, and this order is the only protection against dependency confusion. It finally requires a cache that is really filled, measured after a client has gone through it.

Guided lab Practice

Learn how to do it

Proxy a public index with Nexus, and close the open door

$ dsoxlab run nexus-01-proxy

Environment: VM·Duration: ~40 min

How it is checked: the state of the system is checked after a reboot, not the command you typed.

First time? What DSOXLab is and how to install it

DSOXLab is the command line that prepares a disposable environment (an isolated shell or a VM), runs the lab scenario, then checks the real state of the system and computes a score. Nothing is installed or broken on your workstation.

It needs Python 3.11 or later, uv or pipx, and git. The installation guide details these prerequisites; on Windows, or on a Mac without Python, use the appliance instead.

This lab starts virtual machines: it also needs ansible-playbook, a hypervisor (KVM or Incus), Terraform and hardware virtualization (/dev/kvm), which inside a VirtualBox VM means nested virtualization. The first time, dsoxlab start nexus-01-proxy checks all of it before creating the machines. Prepare your machine for vm labs.

Install the CLI and add the catalogue, once:

uv tool install dsoxlab   # or: pipx install dsoxlab
dsoxlab catalog add https://github.com/stephrobert/artefacts-dsoxlab-training

Before you run the lab, check:

• DSOXLab installed
• catalogue available
• compatible environment (isolated shell or VM)

To check, nothing is probed from this page: run dsoxlab doctor. Read the diagnosis

Run this lab, then validate your work:

dsoxlab run nexus-01-proxy
dsoxlab check nexus-01-proxy

See every lab: dsoxlab list-labs. Track your progress: dsoxlab progress. The full dsoxlab guide covers scoring and the pitfalls.

Troubleshooting

Symptom	Likely cause	Solution
The proxy returns 404 on a package	Wrong repository path	Check the /repository/<name>/ URL
Nothing gets cached	Request on the index only	The cache stores the downloaded artifacts, not the index pages
The proxy is "auto-blocked"	Upstream repository unreachable	Nexus restores it on its own as soon as upstream answers; to avoid waiting, unblock it from the repository's page
pip ignores Nexus	Wrong configuration file	Check index-url in pip.conf

Swipe to see more

Key takeaways

• A proxy repository caches a public repository on first download (pull-through cache).
• It brings speed, resilience (auto-blocking) and visibility into the dependencies consumed.
• The maximum component age sets how often upstream is rechecked (-1 for immutable releases).
• You expose a group repository (hosted before proxy), not the proxy directly: a single URL and a protection against dependency confusion.
• Cleanup policies prune the cache to keep storage under control and stay under the quota; they must be assigned to a repository.

Knowledge check

Eight questions on the pull-through cache: what gets cached and what does not, what auto blocking does, and why clients point at a group.

Knowledge check

Check what you have learned with this interactive quiz

8 questions

8 min

70% to pass

How it works

• The timer starts when you click Start
• Multiple choice, true/false and short answer questions
• You can move between questions
• Detailed results are shown at the end

Start the quiz

Starts the quiz and the timer

×

See in the glossary →