[GH-ISSUE #5258] Add Python PIP Index Configuration via Environment Variables to Prevent Startup Failures #3150

New issue

Open

opened 2026-02-26 07:37:58 +03:00 by kerem · 0 comments

kerem commented

2026-02-26 07:37:58 +03:00

Owner

Originally created by @AndroidOL on GitHub (Jan 31, 2026).
Original GitHub issue: https://github.com/NginxProxyManager/nginx-proxy-manager/issues/5258

Is your feature request related to a problem? Please describe.

Yes, there is a critical problem where the Nginx Proxy Manager (NPM) Docker container fails to start properly when it cannot download required pip packages. During container startup, NPM attempts to install certbot plugins (e.g., certbot-dns-aliyun) via pip. If the network connection to the default PyPI repository is unstable or blocked, pip installation hangs or fails with SSL errors. This prevents the NPM web interface and all proxy functionalities from starting, rendering the service completely unusable until pip can successfully download the packages. In some network environments, this may take an indefinite amount of time (days or even months), effectively breaking the service.

Describe the solution you'd like

I request the addition of environment variables to allow users to configure custom pip indexes/mirrors. Specifically, please add support for:

PIP_INDEX_URL: To set the primary PyPI index URL (e.g., https://pypi.tuna.tsinghua.edu.cn/simple)
PIP_EXTRA_INDEX_URL: To set extra index URLs (e.g., for fallback mirrors)
PIP_TRUSTED_HOST: To optionally trust custom hosts (if using HTTP or self-signed certificates)

These variables should be respected during the container's startup sequence when pip installs certbot plugins. This change will enable users in regions with poor connectivity to PyPI to use reliable mirrors, ensuring the container starts reliably and quickly.

Describe alternatives you've considered

Manual intervention after each restart: Logging into the container and running pip install with -i option, but this is not sustainable and requires the container to be running (which it isn't if startup fails).
Building a custom Docker image: Modifying the Dockerfile to include pip configuration, but this breaks the ease of use of the official image and requires maintaining forks.
Using a corporate proxy or VPN: This may not be available to all users and adds complexity.
Pre-downloading plugins and mounting volumes: Could work but is cumbersome and not officially supported.

Additional context

The error logs clearly show SSL connection failures when accessing https://pypi.org/simple/. This is a common issue in certain geographic regions. The current implementation offers no way to override pip's source, leading to a complete service outage. Adding these environment variables is a standard practice in many Docker images (e.g., Python official images) and would greatly improve the resilience and user experience of Nginx Proxy Manager.

Example of the startup failure log:

[1/31/2026] [8:41:59 AM] [Migrate  ] › ℹ  info      Current database version: none

[1/31/2026] [8:41:59 AM] [Certbot  ] › ▶  start     Installing aliyun...

[1/31/2026] [8:43:12 AM] [Certbot  ] › ✖  error     WARNING: Retrying (Retry(total=4, connect=None, read=None, redirect=None, status=None)) after connection broken by 'SSLError(SSLZeroReturnError(6, 'TLS/SSL connection has been closed (EOF) (_ssl.c:992)'))': /simple/certbot-dns-aliyun/

WARNING: Retrying (Retry(total=3, connect=None, read=None, redirect=None, status=None)) after connection broken by 'SSLError(SSLZeroReturnError(6, 'TLS/SSL connection has been closed (EOF) (_ssl.c:992)'))': /simple/certbot-dns-aliyun/

WARNING: Retrying (Retry(total=2, connect=None, read=None, redirect=None, status=None)) after connection broken by 'SSLError(SSLZeroReturnError(6, 'TLS/SSL connection has been closed (EOF) (_ssl.c:992)'))': /simple/certbot-dns-aliyun/

WARNING: Retrying (Retry(total=1, connect=None, read=None, redirect=None, status=None)) after connection broken by 'SSLError(SSLZeroReturnError(6, 'TLS/SSL connection has been closed (EOF) (_ssl.c:992)'))': /simple/certbot-dns-aliyun/

WARNING: Retrying (Retry(total=0, connect=None, read=None, redirect=None, status=None)) after connection broken by 'SSLError(SSLZeroReturnError(6, 'TLS/SSL connection has been closed (EOF) (_ssl.c:992)'))': /simple/certbot-dns-aliyun/

ERROR: Could not find a version that satisfies the requirement certbot-dns-aliyun~=2.0.0 (from versions: none)

ERROR: No matching distribution found for certbot-dns-aliyun~=2.0.0



[1/31/2026] [8:43:12 AM] [Global   ] › ✖  error     Startup Error: Some plugins failed to install. Please check the logs above [Error: Some plugins failed to install. Please check the logs above] {

  previous: undefined,

  code: 1,

  public: false

}

Originally created by @AndroidOL on GitHub (Jan 31, 2026). Original GitHub issue: https://github.com/NginxProxyManager/nginx-proxy-manager/issues/5258 **Is your feature request related to a problem? Please describe.** Yes, there is a critical problem where the Nginx Proxy Manager (NPM) Docker container fails to start properly when it cannot download required pip packages. During container startup, NPM attempts to install certbot plugins (e.g., `certbot-dns-aliyun`) via pip. If the network connection to the default PyPI repository is unstable or blocked, pip installation hangs or fails with SSL errors. This prevents the NPM web interface and all proxy functionalities from starting, rendering the service completely unusable until pip can successfully download the packages. In some network environments, this may take an indefinite amount of time (days or even months), effectively breaking the service. **Describe the solution you'd like** I request the addition of environment variables to allow users to configure custom pip indexes/mirrors. Specifically, please add support for: - `PIP_INDEX_URL`: To set the primary PyPI index URL (e.g., `https://pypi.tuna.tsinghua.edu.cn/simple`) - `PIP_EXTRA_INDEX_URL`: To set extra index URLs (e.g., for fallback mirrors) - `PIP_TRUSTED_HOST`: To optionally trust custom hosts (if using HTTP or self-signed certificates) These variables should be respected during the container's startup sequence when pip installs certbot plugins. This change will enable users in regions with poor connectivity to PyPI to use reliable mirrors, ensuring the container starts reliably and quickly. **Describe alternatives you've considered** - **Manual intervention after each restart**: Logging into the container and running pip install with `-i` option, but this is not sustainable and requires the container to be running (which it isn't if startup fails). - **Building a custom Docker image**: Modifying the Dockerfile to include pip configuration, but this breaks the ease of use of the official image and requires maintaining forks. - **Using a corporate proxy or VPN**: This may not be available to all users and adds complexity. - **Pre-downloading plugins and mounting volumes**: Could work but is cumbersome and not officially supported. **Additional context** The error logs clearly show SSL connection failures when accessing `https://pypi.org/simple/`. This is a common issue in certain geographic regions. The current implementation offers no way to override pip's source, leading to a complete service outage. Adding these environment variables is a standard practice in many Docker images (e.g., Python official images) and would greatly improve the resilience and user experience of Nginx Proxy Manager. Example of the startup failure log: ``` [1/31/2026] [8:41:59 AM] [Migrate ] › ℹ info Current database version: none [1/31/2026] [8:41:59 AM] [Certbot ] › ▶ start Installing aliyun... [1/31/2026] [8:43:12 AM] [Certbot ] › ✖ error WARNING: Retrying (Retry(total=4, connect=None, read=None, redirect=None, status=None)) after connection broken by 'SSLError(SSLZeroReturnError(6, 'TLS/SSL connection has been closed (EOF) (_ssl.c:992)'))': /simple/certbot-dns-aliyun/ WARNING: Retrying (Retry(total=3, connect=None, read=None, redirect=None, status=None)) after connection broken by 'SSLError(SSLZeroReturnError(6, 'TLS/SSL connection has been closed (EOF) (_ssl.c:992)'))': /simple/certbot-dns-aliyun/ WARNING: Retrying (Retry(total=2, connect=None, read=None, redirect=None, status=None)) after connection broken by 'SSLError(SSLZeroReturnError(6, 'TLS/SSL connection has been closed (EOF) (_ssl.c:992)'))': /simple/certbot-dns-aliyun/ WARNING: Retrying (Retry(total=1, connect=None, read=None, redirect=None, status=None)) after connection broken by 'SSLError(SSLZeroReturnError(6, 'TLS/SSL connection has been closed (EOF) (_ssl.c:992)'))': /simple/certbot-dns-aliyun/ WARNING: Retrying (Retry(total=0, connect=None, read=None, redirect=None, status=None)) after connection broken by 'SSLError(SSLZeroReturnError(6, 'TLS/SSL connection has been closed (EOF) (_ssl.c:992)'))': /simple/certbot-dns-aliyun/ ERROR: Could not find a version that satisfies the requirement certbot-dns-aliyun~=2.0.0 (from versions: none) ERROR: No matching distribution found for certbot-dns-aliyun~=2.0.0 [1/31/2026] [8:43:12 AM] [Global ] › ✖ error Startup Error: Some plugins failed to install. Please check the logs above [Error: Some plugins failed to install. Please check the logs above] { previous: undefined, code: 1, public: false } ```

kerem added the

enhancement

label

2026-02-26 07:37:58 +03:00

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

starred/nginx-proxy-manager-NginxProxyManager#3150

No description provided.

Rows
Columns