Client Configuration

Client Configuration

This guide covers how to configure each package manager to use the registry proxy. All examples assume the registry is running at https://packages.example.com. Replace this with your actual registry URL.

Python — pip

One-off install

pip install --index-url https://packages.example.com/simple/ requests

If the registry uses HTTP (not HTTPS), add --trusted-host:

pip install --index-url http://packages.example.com/simple/ --trusted-host packages.example.com requests

Permanent configuration

Create or edit ~/.pip/pip.conf (Linux/macOS) or %APPDATA%\pip\pip.ini (Windows):

[global]
index-url = https://packages.example.com/simple/
trusted-host = packages.example.com

Environment variable

export PIP_INDEX_URL=https://packages.example.com/simple/
export PIP_TRUSTED_HOST=packages.example.com

pip install requests

Per-project (requirements file)

Add at the top of your requirements.txt:

--index-url https://packages.example.com/simple/
requests==2.31.0
django==4.2

With authentication

pip install --index-url https://user:password@packages.example.com/simple/ requests

Or in pip.conf:

[global]
index-url = https://user:password@packages.example.com/simple/

Python — uv

One-off install

uv pip install --index-url https://packages.example.com/simple/ requests

Or when using uv add in a project:

uv add --index-url https://packages.example.com/simple/ requests

Environment variable

export UV_INDEX_URL=https://packages.example.com/simple/

uv pip install requests
uv add django

Per-project (pyproject.toml)

[tool.uv]
index-url = "https://packages.example.com/simple/"

Or using the newer index configuration:

[[tool.uv.index]]
name = "private"
url = "https://packages.example.com/simple/"
default = true

With authentication

export UV_INDEX_URL=https://user:password@packages.example.com/simple/
uv pip install requests

Or via per-index credentials:

export UV_INDEX_PRIVATE_USERNAME=user
export UV_INDEX_PRIVATE_PASSWORD=password

JavaScript — npm

One-off install

npm install --registry https://packages.example.com lodash

Environment variable

export NPM_CONFIG_REGISTRY=https://packages.example.com

npm install lodash

Permanent configuration (.npmrc)

Create or edit ~/.npmrc for user-wide configuration:

registry=https://packages.example.com/

Or create .npmrc in the project root for per-project configuration:

registry=https://packages.example.com/

Scoped packages

Route only packages under a specific scope to the registry:

# .npmrc
@myorg:registry=https://packages.example.com/

This routes @myorg/* packages through the proxy while everything else uses the default npm registry.

With authentication

# .npmrc
registry=https://packages.example.com/
//packages.example.com/:_authToken=your-token-here

Or use login:

npm login --registry https://packages.example.com

Publishing

npm publish --registry https://packages.example.com

Or in package.json:

{
  "publishConfig": {
    "registry": "https://packages.example.com/"
  }
}

JavaScript — yarn

Yarn Classic (v1)

yarn add lodash --registry https://packages.example.com

Permanent configuration via ~/.npmrc (yarn classic reads .npmrc):

registry=https://packages.example.com/

Yarn Berry (v2+)

One-off (set per-project):

yarn config set npmRegistryServer https://packages.example.com
yarn add lodash

This writes to .yarnrc.yml:

npmRegistryServer: "https://packages.example.com"

For HTTP registries (non-TLS), also configure:

yarn config set unsafeHttpWhitelist '["packages.example.com"]' --json
yarn config set enableStrictSsl false

Scoped packages (Yarn Berry)

# .yarnrc.yml
npmScopes:
  myorg:
    npmRegistryServer: "https://packages.example.com"

With authentication (Yarn Berry)

# .yarnrc.yml
npmRegistries:
  "https://packages.example.com":
    npmAuthToken: "your-token-here"

JavaScript — pnpm

One-off install

pnpm add lodash --registry https://packages.example.com

Environment variable

export NPM_CONFIG_REGISTRY=https://packages.example.com

pnpm add lodash

Permanent configuration

pnpm reads .npmrc in the same format as npm:

# ~/.npmrc or project .npmrc
registry=https://packages.example.com/

Scoped packages

# .npmrc
@myorg:registry=https://packages.example.com/

With authentication

# .npmrc
registry=https://packages.example.com/
//packages.example.com/:_authToken=your-token-here

CI/CD Examples

GitHub Actions

- name: Install Python dependencies
  env:
    PIP_INDEX_URL: https://packages.example.com/simple/
  run: pip install -r requirements.txt

- name: Install Node dependencies
  env:
    NPM_CONFIG_REGISTRY: https://packages.example.com
  run: npm ci

GitLab CI

variables:
  PIP_INDEX_URL: https://packages.example.com/simple/
  NPM_CONFIG_REGISTRY: https://packages.example.com

install:
  script:
    - pip install -r requirements.txt
    - npm ci

Docker build

# Python
FROM python:3.12
ARG PIP_INDEX_URL=https://packages.example.com/simple/
RUN pip install requests django

# Node
FROM node:20
RUN npm config set registry https://packages.example.com
COPY package*.json ./
RUN npm ci

Verifying the Proxy

To confirm packages are being served through the registry proxy:

Check the simple index (PyPI)

curl https://packages.example.com/simple/

Check package metadata (npm)

curl https://packages.example.com/lodash | python3 -m json.tool | head -20

Check cached packages

# PyPI packages
curl https://packages.example.com/api/v1/packages

# npm packages
curl https://packages.example.com/api/v1/npm/packages

Health check

curl https://packages.example.com/healthz