Skip to content
Back to top

# 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 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

- Troubleshooting for more problem-solving tips

- Environment Variables for a complete list of environment variables

- pip documentation for more pip configuration options