DEV Community

niuniu
niuniu

Posted on

Quick Tip: `python3 -m pip` Has a Hidden `debug` Command That Diagnoses 90% of Install Failures

#python #coding #tips

Quick Tip

pip install fails with "no matching distribution found" and the advice online is always "upgrade pip" or "recreate the venv." Nine times out of ten the real answer is in one command nobody talks about:

python3 -m pip debug --verbose
Enter fullscreen mode Exit fullscreen mode

It prints three things that matter:

sys.implementation:
  name: cpython
compatible tags:
  cp311-cp311-manylinux_2_36_x86_64
  cp311-abi3-manylinux_2_36_x86_64
  ...
Enter fullscreen mode Exit fullscreen mode

1. Your compatible wheel tags. If the package only ships cp310 wheels and you're on cp311, that's the whole bug. No reinstall will fix it.

2. Which interpreter pip actually belongs to:

python3 -m pip debug --verbose | grep -m1 'sys.executable'
Enter fullscreen mode Exit fullscreen mode

If that path isn't the venv you think you're in, you've been installing into the wrong Python the whole time.

3. glibc version for manylinux wheels. manylinux_2_36 vs manylinux2014 mismatches on older distros are why "works on my laptop" dies on the server.

The 10-second workflow before touching anything:

python3 -m pip debug --verbose | head -40
python3 -c "import sys; print(sys.version)"
Enter fullscreen mode Exit fullscreen mode

Compare the tag list against the files on the package's PyPI download page. Mismatch = you need a different Python version or an older package pin, not a bigger hammer.

Saved me from reinstalling Python twice this month alone.

What pip error cost you the most time before you found the actual cause?

Powered by MonkeyCode (free AI pair programmer): https://ly.cyberserval.tech/iIETXiF

Top comments (0)