Analysis and Resolution of Python pip NewConnectionError with DNS Configuration

Error Phenomenon and Initial Analysis

When using the pip3 install numpy command to install Python libraries on a Linux server, the system repeatedly encounters NewConnectionError. The error message indicates: Failed to establish a new connection: [Errno -2] Name or service not known, showing that the system cannot establish a new connection to the PyPI server. The error log shows pip performed multiple retries (from total=4 down to total=0) but ultimately failed to find a version satisfying the numpy requirement.

Network Diagnostics and Problem Identification

Further network diagnostic tests revealed the following key observations:

• The ping google.com command returns Name or service not known error
• The ping 8.8.8.8 command communicates normally, showing stable network connectivity

This contrast indicates that the system can perform IP-level network communication but cannot resolve domain names. This strongly points to DNS (Domain Name System) configuration issues rather than basic network connectivity problems.

DNS Resolution Mechanism and Error Root Cause

DNS is a fundamental internet service responsible for translating human-readable domain names (such as pypi.org) into machine-recognizable IP addresses. When pip attempts to download packages from the PyPI repository, it first needs to resolve the domain name of the repository server. The system completes this resolution process by querying DNS servers configured in the /etc/resolv.conf file.

In the current error scenario, the system's DNS configuration may have issues:

• DNS servers are unreachable or misconfigured
• DNS cache pollution or configuration absence
• Network policies restricting DNS queries

Core Solution: Configuring Google Public DNS

The most effective solution is to modify the system's DNS configuration to use reliable public DNS servers. Specific operational steps are as follows:

1. Open the DNS configuration file using a text editor: sudo nano /etc/resolv.conf
2. Add Google's public DNS server to the file: nameserver 8.8.8.8
3. Save the file and exit the editor
4. Verify the configuration takes effect: ping google.com

Google's 8.8.8.8 DNS server provides stable, fast domain name resolution services, effectively solving most DNS-related problems. After configuration, pip should be able to normally connect to the PyPI server and complete library installation.

Alternative Solutions and Applicable Scenarios

In addition to the primary DNS configuration solution, other answers provide alternative solutions for specific environments:

Proxy Network Environments

In enterprise or institutional networks where systems access external networks through proxy servers, pip's proxy parameters can be used:

pip install --proxy="proxy_ip:port" numpy

For example: pip install --proxy="10.50.225.80:3128" numpy

Network Service Restart

In some cases, restarting network management services may resolve temporary network configuration issues:

systemctl restart NetworkManager.service

Preventive Measures and Best Practices

To prevent similar problems from recurring, the following preventive measures are recommended:

• Configure multiple reliable DNS servers (such as 8.8.8.8 and 8.8.4.4) during system deployment
• Regularly check the integrity and correctness of network configuration files
• Ensure correct DNS configuration transmission in containerized environments
• Establish network connectivity test scripts to regularly verify the accessibility of key services

In-depth Technical Principle Analysis

From a technical perspective, pip's installation process involves multiple network layers:

1. DNS Resolution Phase: pip needs to resolve the domain name address of the PyPI repository
2. TCP Connection Establishment: Establish HTTPS connection with the resolved IP address
3. Data Transmission: Download package metadata and actual package files

NewConnectionError occurs in the first phase, where DNS resolution failure prevents obtaining the target server's IP address. The urllib3 library (pip's underlying HTTP client) automatically retries when connections cannot be established, but DNS resolution failure renders all retries ineffective.

Conclusion

Python pip's NewConnectionError typically originates from DNS configuration issues rather than network connectivity itself. By configuring reliable public DNS servers (such as Google's 8.8.8.8), this problem can be quickly and effectively resolved. Understanding DNS resolution mechanisms and network configuration principles is crucial for system management and troubleshooting. In complex network environments, factors such as proxy configurations and network service status must also be considered, adopting comprehensive solutions.