---
title: "Upstream proxy"
description: "An upstream proxy is a registry that fetches packages from an external source on demand and serves them to your builds. Think of it…"
canonical_url: "https://cloudsmith.com/resources/glossary/upstream-proxy"
last_updated: "2026-10-16T14:52:16Z"
---
# Upstream proxy

## What Is an Upstream Proxy?

An upstream proxy is a registry that fetches packages from an external source on demand and serves them to your builds. Think of it as a trusted middleman between your developers and public registries such as npm, PyPI or Maven Central.

## How an Upstream Proxy Works

```json
{
  "_key": "740f8683-99e",
  "_type": "tableBlock",
  "firstRowIsHeader": true,
  "markDefs": null,
  "table": {
    "rows": [
      {
        "_key": "694b1f14-e73",
        "_type": "tableRow",
        "cells": [
          "Step",
          "What happens"
        ]
      },
      {
        "_key": "693a166b-b11",
        "_type": "tableRow",
        "cells": [
          "Request",
          "A build asks the proxy for a package"
        ]
      },
      {
        "_key": "5171e807-f7f",
        "_type": "tableRow",
        "cells": [
          "Lookup",
          "The proxy checks its local store, then configured upstream sources in priority order"
        ]
      },
      {
        "_key": "8eab9986-9d3",
        "_type": "tableRow",
        "cells": [
          "Fetch",
          "If the package is missing, the proxy retrieves it from the upstream source"
        ]
      },
      {
        "_key": "17e192ea-79a",
        "_type": "tableRow",
        "cells": [
          "Serve",
          "The package is returned to the client, and may be cached for later requests"
        ]
      }
    ]
  }
}
```

## Why Upstream Proxies Matter

Routing dependencies through one point brings several benefits:

- Builds keep working during public registry outages
- Packages removed upstream stay available
- One place to see what teams consume
- A point to apply security and license checks

Visibility and control come from the same change.

## Proxying vs Caching

**Proxying** passes each request through to the upstream source. **Caching** stores a copy so later requests are served locally. Most proxies do both, and caching is what protects builds when the source goes down.

## Final Thought

An upstream proxy turns public registries from a direct dependency into a managed one. It makes external packages predictable.

## Frequently asked questions

### Is an upstream proxy the same as a mirror?

Not quite. A mirror copies an entire source in advance, while a proxy fetches only the packages that are requested.

### Does an upstream proxy make dependencies safe?

No. It centralizes access, but safety depends on the scanning and policy checks applied to what it serves.

### Can an upstream proxy cause stale packages?

It can if cached metadata is not refreshed. Most proxies let you set how long cached data is trusted.

### Which package formats can be proxied?

Common examples include npm, Python, Maven, Go, NuGet and container images. Support varies by tool.

### What happens when two upstreams have the same package?

The proxy follows a configured priority order, so the higher-priority source wins.