Skip to content

corporate-environments.rst

Latest commit

 

History

History
349 lines (219 loc) · 8.63 KB

corporate-environments.rst

File metadata and controls

349 lines (219 loc) · 8.63 KB
Raw

Corporate Environments

This guide covers common scenarios when using build behind corporate firewalls, with private package indexes (custom package repositories), or in restricted network environments.

Private package indexes

Using a private PyPI mirror

Set the PIP_INDEX_URL environment variable to point to your private package index (an alternative to PyPI):

$ export PIP_INDEX_URL=https://pypi.company.com/simple
$ python -m build

Or for a single command:

$ PIP_INDEX_URL=https://pypi.company.com/simple python -m build

Additional indexes

To use both PyPI and a private index:

$ export PIP_INDEX_URL=https://pypi.org/simple
$ export PIP_EXTRA_INDEX_URL=https://pypi.company.com/simple
$ python -m build

Warning

Using PIP_EXTRA_INDEX_URL has security implications. A malicious package on any index can shadow packages from other indexes. Use PIP_INDEX_URL exclusively when possible.

Authentication

Embedded credentials

You can embed credentials directly in the index URL:

$ PIP_INDEX_URL=https://username:password@pypi.company.com/simple python -m build

Warning

Be careful with embedded credentials in shell history and CI logs. Use environment variable substitution when possible:

$ PIP_INDEX_URL=https://${PYPI_USER}:${PYPI_TOKEN}@pypi.company.com/simple python -m build

Using keyring

Build passes --no-input to pip, preventing hidden credential prompts that cause the process to appear stuck. When the keyring CLI is available on PATH, build automatically sets PIP_KEYRING_PROVIDER=subprocess (or UV_KEYRING_PROVIDER=subprocess when using the uv installer) so the installer delegates credential lookups to the system keyring without needing keyring installed inside the isolated build environment.

Install keyring system-wide so it is available on PATH:

$ pipx install keyring

Or install build with the keyring extra:

$ pip install build[keyring]

Then store your credentials:

$ keyring set https://pypi.company.com username

For specialized backends (e.g., Google Artifact Registry, Azure Artifacts), install the corresponding keyring plugin alongside keyring:

$ pipx install keyring
$ pipx inject keyring keyrings.google-artifactregistry-auth

You can also set the keyring provider explicitly via environment variable, which is useful in CI or when keyring is installed in a non-standard location:

$ export PIP_KEYRING_PROVIDER=subprocess  # for pip installer
$ export UV_KEYRING_PROVIDER=subprocess   # for uv installer
$ python -m build

To disable keyring entirely:

$ export PIP_KEYRING_PROVIDER=disabled
$ export UV_KEYRING_PROVIDER=disabled
$ python -m build

Using .netrc

Create a ~/.netrc file (~/_netrc on Windows) with your credentials:

machine pypi.company.com
login username
password your-password

Ensure the file has restricted permissions:

$ chmod 600 ~/.netrc

SSL/TLS certificates

Custom CA certificates

If your company uses a custom CA certificate:

$ export REQUESTS_CA_BUNDLE=/path/to/company-ca-bundle.crt
$ python -m build

Or use pip's certificate option:

$ export PIP_CERT=/path/to/company-ca-bundle.crt
$ python -m build

Self-signed certificates

For development environments with self-signed certificates (not recommended for production):

$ export PIP_TRUSTED_HOST=pypi.company.com
$ python -m build

Using virtualenv for better SSL support

If you encounter SSL/TLS errors with Python's built-in venv, install virtualenv:

$ pip install build[virtualenv]

This provides a more recent version of pip with better SSL support and truststore capabilities.

Note

Python 3.11.8+ and 3.12.2+ have improved SSL support and may not need this workaround.

Proxy servers

HTTP/HTTPS proxies

Configure proxy environment variables:

$ export HTTP_PROXY=http://proxy.company.com:8080
$ export HTTPS_PROXY=http://proxy.company.com:8080
$ python -m build

With authentication:

$ export HTTP_PROXY=http://user:pass@proxy.company.com:8080
$ export HTTPS_PROXY=http://user:pass@proxy.company.com:8080

No proxy for certain hosts

$ export NO_PROXY=localhost,127.0.0.1,.company.com
$ python -m build

pip configuration files

Global configuration

Instead of environment variables, you can create a pip configuration file.

On Linux/macOS (~/.config/pip/pip.conf):

[global]
index-url = https://pypi.company.com/simple
trusted-host = pypi.company.com
cert = /path/to/company-ca-bundle.crt

On Windows (%APPDATA%\pip\pip.ini):

[global]
index-url = https://pypi.company.com/simple
trusted-host = pypi.company.com
cert = C:\\path\\to\\company-ca-bundle.crt

Per-project configuration

Create a pip.conf file in your project directory. This is useful for team settings.

Air-gapped environments

For completely offline builds, you must manually install dependencies first:

$ pip install setuptools wheel your-build-backend
$ python -m build --no-isolation

The --no-isolation flag tells build to use your current environment instead of creating an isolated one.

Warning

When using --no-isolation, ensure all build dependencies are installed and compatible.

CI/CD environments

GitHub Actions

- name: Build package
  run: python -m build
  env:
    PIP_INDEX_URL: ${{ secrets.PYPI_INDEX_URL }}
    PIP_CERT: /path/to/cert.crt

GitLab CI

build:
  script:
    - export PIP_INDEX_URL=$PYPI_INDEX_URL
    - python -m build

Catching backend warnings

To catch deprecation warnings from your build backend (useful in CI):

$ PYTHONWARNINGS=error::DeprecationWarning python -m build

Or for setuptools specifically:

$ PYTHONWARNINGS=error:::setuptools.config.setupcfg python -m build

See :doc:`troubleshooting` for more details on warnings.

Common issues

Build fails with authentication errors

Build passes --no-input to pip to prevent hidden credential prompts. If your private index requires authentication, pip will fail instead of hanging. Configure one of the authentication methods above (embedded credentials, keyring, or .netrc) to provide credentials non-interactively.

401/403 errors

Authentication failed. Verify your credentials and ensure they have access to the required packages.

SSL verification failed

Your system doesn't trust the certificate. Use REQUESTS_CA_BUNDLE or PIP_CERT to provide the CA certificate, or install build[virtualenv] for better SSL support.

Conda environment conflicts

If you're in a conda environment and experiencing venv creation issues:

$ conda deactivate
$ python -m build

Or use virtualenv:

$ pip install build[virtualenv]
$ python -m build

See also