pypi-lockdown

Bootstrap a Python environment so that all packages are pulled from an internal, authenticated PyPI feed. Install this package first, then every subsequent pip install / uv add will use the configured feed — with artifacts-keyring handling credentials transparently.

📖 Full setup guide — covers uv, pip, conda, CI pipelines, Docker, GitHub Actions, and devcontainers.

Quick start

# 1. Create & activate a fresh environment
python -m venv .venv && source .venv/bin/activate   # venv (Linux / macOS)
python -m venv .venv && .venv\Scripts\activate       # venv (Windows)
conda create -n myenv python && conda activate myenv # conda

# 2. Install pypi-lockdown from the public feed
pip install pypi-lockdown \
    --index-url https://pkgs.dev.azure.com/ORG/PROJECT/_packaging/PUBLIC_FEED/pypi/simple/

# 3. Lock down the environment to use the authenticated feed
python -m pypi_lockdown \
    https://pkgs.dev.azure.com/ORG/PROJECT/_packaging/PRIVATE_FEED/pypi/simple/

# 4. Done — all future installs use the authenticated feed
pip install requests   # resolved from PRIVATE_FEED, authenticated via artifacts-keyring

Standalone .pyz (build locally)

For environments where you can't pip install first, you can build a standalone .pyz zipapp that bundles all dependencies:

pip install tox shiv
tox -e standalone -- linux-x86_64    # or macos-universal2, win-amd64
python dist/pypi-lockdown-linux-x86_64.pyz \
    https://pkgs.dev.azure.com/ORG/PROJECT/_packaging/PRIVATE_FEED/pypi/simple/

This writes pip/uv config files and installs artifacts-keyring-nofuss plus all its dependencies into the active environment — no network access to any package feed required.

.pyz files are platform-specific (Linux, macOS, Windows) because cryptography contains native extensions.

What it does

pypi-lockdown writes configuration files that redirect the default package index:

When run inside a project directory (containing pyproject.toml), the tool offers to configure uv, Poetry, and Hatch settings directly in the project file — including keyring-provider and index URLs with the __token__@ prefix that uv requires for keyring authentication. Hatch configuration is only written when an existing [tool.hatch] section is detected.

Works with venv, conda, and any other environment manager that sets VIRTUAL_ENV or CONDA_PREFIX.

Platform-specific config paths

Manual Poetry setup

If you run pypi-lockdown outside a project directory (no pyproject.toml), or decline the prompt, you can configure Poetry manually:

poetry source add --priority=primary internal https://pkgs.dev.azure.com/ORG/PROJECT/_packaging/FEED/pypi/simple/
poetry source add --priority=explicit PyPI

CLI reference

python -m pypi_lockdown [configure] [INDEX_URL] [--user] [--ci] [--verify]
python -m pypi_lockdown verify INDEX_URL
python -m pypi_lockdown scaffold NAME INDEX_URL

Auto-detect feed URL

When INDEX_URL is omitted, pypi-lockdown reads the current directory's pyproject.toml and looks for a configured feed:

1. [[tool.uv.index]] entry with default = true
2. [[tool.poetry.source]] entry with priority = "primary"
3. [tool.hatch.envs.default.env-vars] for PIP_INDEX_URL or UV_DEFAULT_INDEX

This means after initial setup, team members can simply run:

python -m pypi_lockdown

Creating team-specific wrapper packages

Use scaffold to generate a small package that hardcodes your team's feed URL and depends on pypi-lockdown:

python -m pypi_lockdown scaffold ai4s-pypi-lockdown \
    https://pkgs.dev.azure.com/ai4s/ai4s/_packaging/ai4s-pypi/pypi/simple/

This creates a ready-to-publish package:

ai4s-pypi-lockdown/
├── pyproject.toml
├── tox.ini
└── src/ai4s_pypi_lockdown/
    ├── __init__.py
    └── __main__.py

Users of that wrapper only need:

pip install ai4s-pypi-lockdown --index-url https://pkgs.dev.azure.com/.../PUBLIC_FEED/pypi/simple/
python -m ai4s_pypi_lockdown

Scaffolded packages can also build their own standalone .pyz files:

cd ai4s-pypi-lockdown
tox -e standalone       # builds ai4s-pypi-lockdown-{platform}.pyz

Creating a release

Create a GitHub release — the CI workflow builds a wheel and sdist, attaches them to the release, and publishes to the ADO PyPI feed:

gh release create v1.0.0 --generate-notes

To build a standalone .pyz locally (e.g. for air-gapped environments):

pip install tox shiv
tox -e standalone -- linux-x86_64    # or macos-universal2, win-amd64

Security model

• HTTPS required: configure rejects non-HTTPS index URLs — HTTP would expose credentials and package content to network observers.
• Build provenance: Wheel and sdist releases are built in CI with signed build provenance — verify with gh attestation verify <file> --owner microsoft.
• Standalone .pyz integrity: When building .pyz locally for air-gapped use, the build includes zip-slip protection that validates no archive entry escapes the staging directory.
• Narrow config scope: pypi-lockdown only writes index-url to pip/uv/hatch config files. It does not modify global Python settings or install hooks.

License

MIT