Skip to content
Back to top

# Environment Variables

This reference documents environment variables that affect build’s behavior. You can use these to configure private package indexes, proxies, SSL certificates, and other settings.

## Variables Set by build

### `VIRTUAL_ENV`

build sets this variable when creating isolated environments. It contains the absolute path to the temporary virtual environment that build creates for installing dependencies. Build backends can use this to detect they’re running in an isolated environment.

## Package Index Configuration

By default, build uses pip to install build dependencies in isolated environments. Configure pip using these environment variables to work with private package indexes or mirrors. For detailed examples, see Corporate Environments.

Note

These `PIP_*` variables only apply when using the default pip installer. When using `--installer=uv`, configure uv through its own environment variables instead (e.g., `UV_INDEX_URL`, `UV_EXTRA_INDEX_URL`).

### `PIP_INDEX_URL`

Sets the primary package index URL where pip looks for packages. Use this to point to private package repositories or PyPI mirrors. Defaults to `https://pypi.org/simple`.

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

### `PIP_EXTRA_INDEX_URL`

Adds additional package indexes to search beyond the primary index. This allows using both PyPI and a private index simultaneously.

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

Warning

A malicious package on any extra index can shadow packages from other indexes. Use `PIP_INDEX_URL` exclusively when possible for better security.

### `PIP_CERT`

Path to a custom CA certificate bundle for SSL/TLS verification. Use this when your organization uses self-signed certificates or a custom certificate authority. Defaults to system certificates.

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

### `PIP_TRUSTED_HOST`

Disables SSL verification for the specified host. Only use this in secure development environments where SSL certificates aren’t available.

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

Warning

Disabling SSL verification is insecure. Prefer using `PIP_CERT` with proper certificates.

## Network Configuration

### `PIP_TIMEOUT`

Sets the timeout in seconds for network operations. Increase this on slow or unreliable network connections. Defaults to 15 seconds.

    $ export PIP_TIMEOUT=60
    $ python -m build

### `PIP_RETRIES`

Number of times pip retries failed downloads. Increase this on unstable network connections. Defaults to 5 retries.

    $ export PIP_RETRIES=10
    $ python -m build

### `PIP_NO_CACHE_DIR`

Disables pip’s package cache directory, forcing fresh downloads every time. Useful in CI environments to ensure completely clean builds, though this makes builds slower.

    $ export PIP_NO_CACHE_DIR=1
    $ python -m build

## Proxy Configuration

If you’re behind a corporate proxy, configure these variables to route pip’s network requests through your proxy server. Both uppercase and lowercase versions are recognized.

### `HTTP_PROXY` / `http_proxy`

Proxy server for HTTP requests. Specify the proxy URL including protocol and port.

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

### `HTTPS_PROXY` / `https_proxy`

Proxy server for HTTPS requests. Even though the proxy URL uses `http://`, this handles HTTPS traffic.

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

### `NO_PROXY` / `no_proxy`

Comma-separated list of hosts that should bypass the proxy. Use this for internal servers that don’t require proxy access.

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

## SSL/TLS Certificate Configuration

These variables configure SSL/TLS certificates for secure connections. Use them when your organization uses self-signed certificates or custom certificate authorities.

### `REQUESTS_CA_BUNDLE`

Path to custom CA certificate bundle. The requests library (which pip depends on) uses this variable. Alternative to `PIP_CERT`.

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

### `SSL_CERT_FILE`

Another variable for specifying a custom CA certificate bundle. Recognized by various Python libraries.

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

## Python Runtime Configuration

### `PYTHONWARNINGS`

Controls Python’s warning filters. Use this in CI to catch deprecated features or potential issues in your build configuration by turning warnings into errors.

Catch deprecation warnings:

    $ PYTHONWARNINGS=error::DeprecationWarning python -m build

Catch setuptools-specific warnings:

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

### `PYTHONUTF8`

Enables UTF-8 mode on Windows. Use this when building packages with non-ASCII characters in filenames or file content on Windows systems.

    $ set PYTHONUTF8=1
    $ python -m build

### `TMPDIR` / `TEMP` / `TMP`

Controls where build creates the temporary isolated build environment. Useful for debugging or when you need the temporary directory on a specific filesystem (e.g., for ccache or compilation caching).

On Unix-like systems, use `TMPDIR`:

    $ TMPDIR=/path/to/custom/tmp python -m build

On Windows, use `TEMP`:

    $ set TEMP=C:\path\to\custom\tmp
    $ python -m build

These variables only change where build creates the temporary directory. build still removes its environment when the build ends. To pin the environment to a stable path, or to keep it for inspection, use the `--env-dir` option instead.

Common use cases:

- Disk space: Use a different filesystem with more available space

- Performance: Use faster storage (e.g., tmpfs on Linux)

- Restricted filesystems: Point at the writable part of a read-only container

`TMPDIR` only relocates the base directory; build still appends a random suffix, so the extraction path differs on every run. For compiler caches such as `ccache` or `sccache`, which key on the source path, that random suffix is a guaranteed cache miss - use `--sdist-extract-dir` to pin the path instead.

See Troubleshooting for debugging examples.

## Backend-Specific Variables

Each build backend may define its own environment variables for configuration. Check your backend’s documentation:

- Setuptools

- Hatchling

- PDM-Backend

- Flit

- Poetry-Core

- scikit-build-core

- meson-python

## Non-Isolated Builds

When using `--no-isolation`, build skips creating an isolated environment. All environment variables from your current shell pass directly to the build backend, including:

- `PYTHONPATH` - Affects Python module discovery

- `PATH` - Determines which executables are found

- Any custom variables your build backend uses

build does not set `VIRTUAL_ENV` in this mode. You’re responsible for installing build dependencies yourself. See Basic Usage for appropriate use cases.

## Alternative: Configuration Files

Instead of environment variables, you can configure pip using persistent configuration files. This is convenient if you always use the same settings.

Linux/macOS: `~/.config/pip/pip.conf`

Windows: `%APPDATA%\\pip\\pip.ini`

Example configuration:

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

For more details and examples, see Corporate Environments and the pip configuration documentation.

## See also

- Corporate Environments for proxy and SSL configuration

- Troubleshooting for common issues

- Command-Line Interface for command-line options

- pip documentation for pip configuration