Search guides

Fix pip that will not install

We'll run pip install -v, check network and SSL, fix trusted hosts or certificates—or tell you when to escalate.

Troubleshooting · Servers & Linux
10–25 min
What you'll need
  • Python and pip installed
  • Network access (or proxy config)
Step 1 of 11

Quick triage — pick your path

Get started

Choose the option that matches what you see. You can jump straight to that section.

Show full guide

Steps

Goal: Run pip install -v, check network and SSL, fix trusted hosts or certificates—or escalate.

  • Run pip install -v <package>. Note the exact error.
  • Good: You see a specific error (connection, SSL, 404, permission). Proceed to Check error and connectivity.
  • Bad: pip hangs—check network connectivity and proxy.

Check error and connectivity

Goal: Confirm the error and test index reachability.

  • Run pip config list to see the configured index URL.
  • Test with curl -I https://pypi.org/simple/ or ping pypi.org. If unreachable, check proxy (HTTP_PROXY, HTTPS_PROXY) or firewall.
  • Run df -h and confirm / and ~/.cache/pip have free space.
  • Good: Index is reachable and disk has space. Proceed to Fix SSL or index.
  • Bad: Index unreachable or disk full—fix the index URL, proxy, or free space first.

Fix SSL or index

Goal: Fix SSL certificate errors or wrong index URL.

  • If the error is SSL-related, run pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org <package>. For a custom index, add its host with --trusted-host.
  • If the index URL is wrong, set pip config set global.index-url https://pypi.org/simple/ or use --index-url on the command.
  • If the error is permission denied, create a venv: python -m venv .venv, activate it, then pip install <package>.
  • Good: Install succeeds. Bad: Clear cache with pip cache purge and retry, or escalate.

Clear cache and retry

Goal: Remove corrupted cache and retry.

  • Run pip cache purge or delete ~/.cache/pip. Run python -m pip install --upgrade pip. Retry pip install <package>.
  • Good: Install succeeds. Bad: Escalate with the error and config.

When to escalate

Escalate if:

  • The index is managed by a central team and you cannot change it.
  • The proxy or firewall blocks pip and you cannot change it.
  • The fix requires infrastructure changes outside your control.

Provide: the pip error, pip config list output, and result of curl -I to the index URL.

Verification

  • pip install <package> completes without errors.
  • The package is installed and pip list shows it.
  • No SSL, connection, or permission errors in the output.

Escalation ladder

Work from the device outward. Stop when the problem is fixed.

  1. Capture error Run pip install -v; note exact error.
  2. Connectivity and disk Test index URL with curl; check df -h.
  3. SSL and index Add --trusted-host or fix index-url.
  4. Venv and cache Use virtual environment; clear pip cache.
  5. Escalate Enterprise-managed index or infrastructure change needed.

What to capture if you need help

Before calling support or posting for help, have these ready. It speeds everything up.

  • Exact pip error message
  • Output of pip config list
  • Result of curl -I to index URL
  • df -h and disk usage

Does pip install show a specific error?

Run pip install -v <package> and note the error: connection, SSL, 404, or permission.

Run `pip install -v <package>`. Good: You see a specific error (connection refused, SSL, 404, permission). Bad: pip hangs with no output—check network connectivity.

Yes No (hangs)

You can change your answer later.

Check connectivity and timeouts

Test index URL with `curl -I https://pypi.org/simple/` or `ping pypi.org`. If unreachable, check proxy (HTTP_PROXY, HTTPS_PROXY) or firewall. Check `df -h` for full disk.

Done

Can you reach the index URL?

Test with curl -I. Index must return HTTP 200.

Run `pip config list` and check index-url. Test with `curl -I <index-url>`. Good: HTTP 200 or host reachable. Bad: Timeout or 404—fix index URL or proxy.

Yes No

You can change your answer later.

Fix index URL and retry

Set correct index: `pip config set global.index-url https://pypi.org/simple/` or use `--index-url` on the command. If behind proxy, set HTTP_PROXY and HTTPS_PROXY. Retry `pip install <package>`.

Done

Is disk space sufficient?

pip needs space for downloads and cache.

Run `df -h`. Check `/` and `~/.cache/pip`. Good: At least a few percent free. Bad: Near 100%—free space or expand volume. See fix-linux-runs-out-of-disk.

Yes No

You can change your answer later.

Is the error SSL-related?

SSL: CERTIFICATE_VERIFY_FAILED or similar.

Add `--trusted-host pypi.org --trusted-host files.pythonhosted.org` to the pip command. Or set SSL_CERT_FILE to a valid cert bundle. Good: Install succeeds. Bad: Other error—check permission with venv or fix-linux-has-permission-denied.

Yes No

You can change your answer later.

Add trusted-host and retry

Run `pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org <package>`. For custom index, add its host. Retry install.

Done

Is the error permission denied?

Permission denied when installing to system Python.

Create a venv: `python -m venv .venv`, activate it, then `pip install <package>`. Or use `pip install --user`. Good: Install succeeds. Bad: Clear cache with `pip cache purge` and retry, or escalate.

Yes No

You can change your answer later.

Use virtual environment

Run `python -m venv .venv`, then `source .venv/bin/activate` (Linux) or `.venv\\Scripts\\activate` (Windows). Run `pip install <package>`.

Done

Clear cache and retry

Run `pip cache purge` or delete `~/.cache/pip`. Run `python -m pip install --upgrade pip`. Retry `pip install <package>`.

Done

Escalate

Escalate if the index is enterprise-managed, you cannot change proxy or firewall, or disk cannot be expanded. Provide pip error, pip config list output, and curl test results.

Done

Reviewed by Blackbox Atlas

Frequently asked questions

Why would pip install fail?
Network unreachable, SSL certificate errors, wrong or unreachable index URL, full disk, or permission denied. Run pip install -v to see the exact error.
Can I fix pip install myself?
Yes. Check connectivity, SSL, index URL, disk space, and permissions. Use --trusted-host for SSL issues, --index-url for custom indexes, or a virtual environment for permission issues.
When should I escalate pip install failures?
If the index is enterprise-managed and you cannot change it, or the fix requires proxy or firewall changes outside your control.

Rate this guide

Was this helpful?

Continue to