Skip to content
GProxy
Sign up
Guides 6 Connection Type: 1 views

Using Proxy with Package Managers

This guide explains how to configure proxy settings for popular package managers like npm, pip, and Composer to efficiently manage dependencies.

Python

To use a proxy with package managers like npm, pip, and composer, configure the proxy settings either via environment variables (HTTP_PROXY, HTTPS_PROXY), command-line arguments, or specific configuration files unique to each package manager.

Many development environments operate behind corporate firewalls or require traffic monitoring, necessitating the use of an HTTP or HTTPS proxy server for outbound connections. Package managers, which download dependencies from external registries, must be configured to route their network requests through such proxies to function correctly.

General Proxy Configuration Concepts

Proxy servers can intercept and forward HTTP and HTTPS traffic. Authentication is often required to access these proxies.

Proxy URL Format

The standard format for a proxy URL, including optional authentication, is:

protocol://[user:password@]host:port

  • protocol: http or https
  • user:password: Optional credentials for proxy authentication.
  • host: The proxy server's hostname or IP address.
  • port: The port the proxy server listens on (e.g., 8080, 3128).

Example: http://user:password@proxy.example.com:8080

Environment Variables

The most common and often universally recognized method for configuring proxies across various tools, including package managers, is through standard environment variables.

  • HTTP_PROXY or http_proxy: Specifies the proxy server for HTTP requests.
  • HTTPS_PROXY or https_proxy: Specifies the proxy server for HTTPS requests.
  • NO_PROXY or no_proxy: A comma-separated list of hostnames, domains, or IP addresses that should bypass the proxy. This is crucial for accessing internal resources or local development servers directly.

These variables are typically case-insensitive on Windows but case-sensitive on Unix-like systems. It is common practice to set both UPPER_CASE and lower_case versions for maximum compatibility.

# Example for Unix-like systems (Linux, macOS)
export HTTP_PROXY="http://user:password@proxy.example.com:8080"
export HTTPS_PROXY="http://user:password@proxy.example.com:8080" # Often the same as HTTP_PROXY
export NO_PROXY="localhost,127.0.0.1,.internal.domain.com"

# For Windows Command Prompt
set HTTP_PROXY=http://user:password@proxy.example.com:8080
set HTTPS_PROXY=http://user:password@proxy.example.com:8080
set NO_PROXY=localhost,127.0.0.1,.internal.domain.com

# For Windows PowerShell
$env:HTTP_PROXY="http://user:password@proxy.example.com:8080"
$env:HTTPS_PROXY="http://user:password@proxy.example.com:8080"
$env:NO_PROXY="localhost,127.0.0.1,.internal.domain.com"

npm (Node Package Manager)

npm can be configured using its built-in configuration system or by environment variables.

Configuration via npm config

The preferred method for npm is to set proxy settings directly in its configuration. This stores the settings persistently.

# Set HTTP proxy
npm config set proxy http://user:password@proxy.example.com:8080

# Set HTTPS proxy (often the same as HTTP proxy)
npm config set https-proxy http://user:password@proxy.example.com:8080

# To unset a proxy
npm config rm proxy
npm config rm https-proxy

# Verify settings
npm config get proxy
npm config get https-proxy

If your proxy does not require authentication, omit the user:password@ segment.

SSL Certificate Issues

When using an HTTPS proxy or an HTTPS registry through an HTTP proxy, npm might encounter SSL certificate verification issues. This can occur if the proxy intercepts and re-encrypts HTTPS traffic with its own certificate, which is not trusted by your system.

To address this, you can:
1. Add the proxy's CA certificate to your system's trust store. This is the recommended secure approach.
2. Tell npm to use a specific CA certificate file:
bash npm config set cafile /path/to/proxy/ca-certificate.pem
3. Disable strict SSL verification (not recommended for production):
bash npm config set strict-ssl false
This bypasses certificate validation and can expose you to man-in-the-middle attacks. Use only for temporary debugging in controlled environments.

Registry Configuration

If your organization uses a private npm registry (e.g., Nexus, Artifactory) that is accessible directly or through a different proxy, ensure the registry setting is correct.

npm config set registry https://my-private-registry.example.com/npm/

pip (Python Package Installer)

pip supports proxy configuration via command-line flags, environment variables, or a configuration file.

Command-Line Flag

For a single pip command, use the --proxy flag:

pip install some-package --proxy http://user:password@proxy.example.com:8080

Configuration File

For persistent proxy settings, modify or create the pip configuration file.
* Linux/macOS: ~/.config/pip/pip.conf or ~/.pip/pip.conf
* Windows: %APPDATA%\pip\pip.ini or %HOME%\pip\pip.ini

Add the following to the [global] section:

# ~/.config/pip/pip.conf or %APPDATA%\pip\pip.ini
[global]
proxy = http://user:password@proxy.example.com:8080

Environment Variables

pip respects the standard HTTP_PROXY, HTTPS_PROXY, and NO_PROXY environment variables. If set, these will be used automatically.

export HTTP_PROXY="http://user:password@proxy.example.com:8080"
export HTTPS_PROXY="http://user:password@proxy.example.com:8080"
export NO_PROXY="localhost,127.0.0.1,.internal.domain.com"
pip install some-package

SSL Certificate Issues

Similar to npm, pip can encounter SSL errors.
1. Add proxy's CA certificate to system trust store.
2. Specify a trusted host for the index:
ini # ~/.config/pip/pip.conf or %APPDATA%\pip\pip.ini [global] trusted-host = pypi.org
This tells pip to trust the specified host even if SSL validation fails for it. Use with caution.
3. Specify a custom CA bundle:
ini # ~/.config/pip/pip.conf or %APPDATA%\pip\pip.ini [global] cert = /path/to/proxy/ca-bundle.pem
Or via command line: pip install some-package --cert /path/to/proxy/ca-bundle.pem

Private Package Indexes

If using a private Python package index (e.g., Artifactory, Nexus), configure the index-url or extra-index-url:

# ~/.config/pip/pip.conf or %APPDATA%\pip\pip.ini
[global]
index-url = https://my-private-pypi.example.com/simple/

Composer (PHP Dependency Manager)

Composer relies heavily on environment variables for proxy configuration and may also need Git's proxy settings for repositories fetched via Git.

Environment Variables

Composer primarily uses the standard HTTP_PROXY, HTTPS_PROXY, and NO_PROXY environment variables.

export HTTP_PROXY="http://user:password@proxy.example.com:8080"
export HTTPS_PROXY="http://user:password@proxy.example.com:8080"
export NO_PROXY="localhost,127.0.0.1,.internal.domain.com"
composer install

Composer Configuration (config.json)

While Composer doesn't have a direct proxy setting in its config.json for general HTTP/HTTPS traffic, it's possible to configure proxy settings for specific VCS repositories if they are not picked up by environment variables or if different proxies are needed.

For example, to configure a proxy for Git:

{
    "config": {
        "github-oauth": {
            "github.com": "YOUR_OAUTH_TOKEN"
        }
    }
}

This is not a proxy setting directly, but demonstrates where other network-related configurations might go. For actual Git proxying, see the next section.

Git Proxy Configuration

Composer often fetches packages directly from Git repositories (e.g., GitHub, GitLab). If your Git traffic needs to go through a proxy, you must configure Git itself.

# Set HTTP proxy for Git
git config --global http.proxy http://user:password@proxy.example.com:8080

# Set HTTPS proxy for Git
git config --global https.proxy http://user:password@proxy.example.com:8080

# To unset
git config --global --unset http.proxy
git config --global --unset https.proxy

# Verify
git config --global --get http.proxy
git config --global --get https.proxy

This is especially important if your composer.json uses vcs repositories or direct Git URLs.

SSL Certificate Issues

Composer, like other tools, can face SSL issues.
1. Add proxy's CA certificate to system trust store.
2. Configure Git to disable SSL verification (not recommended):
bash git config --global http.sslVerify false
This should be a last resort and used with extreme caution.

Troubleshooting Common Proxy Issues

  • Incorrect Proxy Address/Port: Double-check the hostname, IP address, and port. A common error is using HTTP for an HTTPS proxy or vice-versa.
  • Authentication Failure: Ensure the username and password in the proxy URL are correct and URL-encoded if they contain special characters.
  • SSL Certificate Errors: If you encounter SSL_ERROR_SYSCALL, certificate verify failed, or similar errors, your proxy might be performing SSL interception. Install the proxy's root CA certificate into your system's trust store or configure the package manager to trust a specific CA bundle (as detailed above).
  • NO_PROXY Issues: If internal services are still trying to go through the proxy, verify your NO_PROXY setting is correct and comprehensive. Ensure it includes localhost, 127.0.0.1, and any relevant internal domain suffixes.
  • Firewall Blocking: Confirm that your machine's firewall or network security groups allow outbound connections to the proxy server's IP and port.
  • Mixed HTTP/HTTPS Configuration: Some proxies handle HTTP and HTTPS differently. Ensure you've configured both HTTP_PROXY and HTTPS_PROXY if applicable, or their specific package manager equivalents.

Comparison of Proxy Configuration Methods

Feature / Manager npm pip composer
Environment Variables Yes (HTTP_PROXY, HTTPS_PROXY) Yes (HTTP_PROXY, HTTPS_PROXY) Yes (HTTP_PROXY, HTTPS_PROXY)
Dedicated Config Command npm config set proxy No direct command for proxy No direct command for proxy
Config File Location ~/.npmrc ~/.config/pip/pip.conf / %APPDATA%\pip\pip.ini No direct proxy setting in composer.json
Command-Line Flag No direct proxy flag --proxy No direct proxy flag
Authentication in URL Yes Yes Yes
SSL Certificate Handling cafile, strict-ssl cert, trusted-host Relies on system/Git config
Git Proxy Dependency No direct dependency No direct dependency Yes (via git config)
Registry URL Setting registry index-url, extra-index-url repositories (in composer.json)
Auto-update: 04.03.2026
All Categories

Advantages of our proxies

25,000+ proxies from 120+ countries

Unlimited Proxies Residential Proxies