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

Install the keyring package to store credentials securely:

$ pip install keyring

Build will automatically use keyring when available. Configure it with:

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

Build will prompt for the password when needed, or you can use:

$ export PYTHON_KEYRING_BACKEND=keyring.backends.null.Keyring  # Disable keyring if needed

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 Troubleshooting for more details on warnings.

Common issues

Build hangs waiting for input

If build appears to hang, it may be waiting for authentication. This happens when pip prompts for credentials but the prompt is hidden.

Solution: Use one of the authentication methods above (embedded credentials, keyring, or .netrc).

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