Configure a PyPI proxy cache for pip and uv

BEFOREhttps://pypi.org/simple

AFTERhttp://localhost:23333/pypi/simple/

pip, uv, Poetry, Pipenv, and PDM all use Depsilo’s /pypi/simple/ endpoint.

The Portal only generates configuration

Select Python and the matching client in the Depsilo Portal to get configuration generated for the current instance address. The Portal displays and copies content; it does not change your machine or project files.

Configure a client

Prefer command, project, or project virtualenv settings. Record the previous index and merge the required fields without replacing existing configuration files.

pip

Start with command options. They apply only to this install and do not write user configuration. Replace requirements.txt with your project’s dependency file:

python -m pip install -r requirements.txt \
  --index-url http://localhost:23333/pypi/simple/ \
  --trusted-host localhost:23333

Omit --trusted-host when using HTTPS with a valid certificate.

For persistent settings, activate the project’s virtualenv and merge the following into its configuration: $VIRTUAL_ENV/pip.conf on Unix/macOS or %VIRTUAL_ENV%\pip.ini on Windows. Use python -m pip config debug to find the location. pip does not automatically read pip.conf from the repository root.

Project virtualenv pip configuration

[global]
index-url = http://localhost:23333/pypi/simple/
# Plain HTTP only:
trusted-host =
    localhost:23333

If trusted-host already has entries, add the Depsilo host and port to that list. [global] means all pip subcommands; the file location determines the configuration scope.

Optional: user-level configuration. Run this only when you want other projects for the current user to use Depsilo:

python -m pip config --user set global.index-url http://localhost:23333/pypi/simple/

Back up the user file first. For HTTP, also merge trusted-host into that file without replacing its existing list. In an activated virtualenv, python -m pip config --site set global.index-url URL explicitly targets that environment. See pip configuration for scope and precedence; bare pip config set does not guarantee a virtualenv-scoped change.

uv

pyproject.toml

[[tool.uv.index]]
name = "depsilo"
url = "http://localhost:23333/pypi/simple/"
default = true

Set default = true so uv resolves packages through Depsilo by default instead of using a public index in parallel.

Poetry

poetry source add --priority=primary depsilo \
  http://localhost:23333/pypi/simple/

The equivalent project configuration is:

pyproject.toml

[[tool.poetry.source]]
name = "depsilo"
url = "http://localhost:23333/pypi/simple/"
priority = "primary"

Do not use extra-index-url as a public fallback

pip considers candidates from multiple indexes together. A public PyPI extra-index-url can bypass a Depsilo policy decision. When every request must be enforced, keep a single controlled entry point and pair it with network egress controls.

Verify the request path

1. Check that the instance is ready

   curl -fsS http://localhost:23333/ready

2. Make a request without changing the environment

   python -m pip install --dry-run --ignore-installed --no-cache-dir --no-deps \
     --index-url http://localhost:23333/pypi/simple/ \
     --trusted-host localhost:23333 six

   This command tests connectivity without installing a package. Omit --trusted-host for HTTPS. pip may only fetch index entries and package metadata; do not assume it downloads a complete wheel or source archive.

3. Confirm the traffic in Admin

   Open Access logs (/admin/logs) in Admin and match the request time, PyPI package, and status. Distinguish index and metadata requests from package files. A successful client command or a local cache hit does not establish a Depsilo artifact cache hit.

4. Verify artifact caching separately

   Verify caching shows how to download an artifact independently of the package manager’s local cache and inspect the matching logs, using an npm tarball as its example. For Python downloads, check the actual wheel or source archive requests rather than index logs. The first download may already be a hit if the server cache is warm.

Use it in CI

Override the index with CI environment variables without rewriting a requirements file. Replace the example hostname with a Depsilo address the runner can actually reach:

export PIP_INDEX_URL=http://depsilo.internal:23333/pypi/simple/
# Plain HTTP only:
export PIP_TRUSTED_HOST=depsilo.internal:23333

python -m pip install -r requirements.txt

If CI runs inside a container, localhost refers to that container, not to Depsilo on the host.

Common issues

Does HTTPS still need trusted-host?

HTTPS with a valid certificate needs no exception. trusted-host allows pip to trust a host without valid HTTPS; this page uses it only for plaintext HTTP examples. After switching to HTTPS, remove only the old Depsilo exception and preserve existing settings for other sources.

How do I roll back?

Command options apply only to that invocation. For persistent settings, restore the previous index in the virtualenv or user file you changed. Remove only the Depsilo trust exception you added and preserve other fields. Do not add a parallel public fallback as a rollback mechanism.

Which endpoint do other Python clients use?

Pipenv and PDM also use /pypi/simple/. Select the matching client in the Portal and copy its project-scoped configuration.

If requests bypass Depsilo or fail with a 451 response, see Troubleshooting.