pip: No matching distribution found for X

Quick fix

Read the commands before running them. Anything that restarts a service, deletes data or changes permissions should be tried on a non-production system first.

# What does pip think it is looking for?
pip debug --verbose | head -30      # supported wheel tags
python -VV

# Ask the index what exists
pip index versions somepackage

# Alpine has no manylinux wheels: musl builds from source
apk add build-base python3-dev
# or use a glibc image
FROM python:3.12-slim

# Private index that shadows PyPI
pip install -i https://pypi.org/simple somepackage

How to diagnose Python errors

Python errors cluster around the import system (which is really about sys.path and the active interpreter), environment management (which interpreter and which site-packages), and concurrency (the GIL, event loops, and pickling constraints in multiprocessing). A very large share of "module not found" reports are simply the wrong interpreter, which is why the first command should always identify it.

If the quick fix above does not resolve it, work through these steps. They apply to this whole class of error, not just to this one message, which is usually what saves the time.

1. Identify the interpreter and its paths: python -c "import sys; print(sys.executable); print(sys.path)". This resolves most import errors immediately.
2. Install into the interpreter you are running, not the one on PATH: python -m pip install … rather than bare pip.
3. Read tracebacks bottom-up. The last line is the exception; the frames above show the call chain, and the relevant frame is usually your code, not the library's.
4. For encoding errors, name the encoding explicitly and decide on an error policy, such as open(path, encoding='utf-8', errors='replace'), rather than relying on the locale default.
5. For multiprocessing pickling errors, move the target function to module level. Closures, lambdas and locally defined classes cannot be pickled.

Tools worth reaching for

• python -m pip
• python -c 'import sys; print(sys.path)'
• pip check
• py-spy dump
• uv / pipx for isolation

Authoritative references

Primary documentation for this error, worth reading before applying any fix in production.

📖 pip.pypa.io

Related Python errors

• asyncio: Task was destroyed but it is pending!The event loop shut down while a task was still running, so its coroutine never got to finish…
• Django: Forbidden (403) CSRF verification failed. Request aborted.Django rejected the POST because the CSRF token or the request Origin did not match the…
• Django: ImproperlyConfigured: setting is not configuredDjango could not find a required setting such as SECRET_KEY, DATABASES, or ALLOWED_HOSTS…
• Django: OperationalError: no such tableThe model exists in code but not in the database. Either migrations were never applied to…
• FastAPI: ResponseValidationErrorThe handler returned data that does not match its response_model. Unlike a request validation…
• pip: SSL Certificate Verify Failedpip cannot verify SSL certificates when downloading packages. Corporate proxy, firewall, or…
• Poetry: pyproject.toml changed significantly since poetry.lock was generatedPoetry stores a hash of the dependency section in the lock file. Editing pyproject.toml by…
• Pydantic v2: ValidationError after upgrade from v1Pydantic v2 is stricter and renamed much of the API. Common breakages: implicit type coercion…

See all 35 Python errors →

Browse other categories

• HTTP 494xx client errors, 5xx server errors, redirects, headers and protocol problems.
• JavaScript 42npm resolution, async pitfalls, hydration, memory limits and runtime type…
• Database 41Connections, deadlocks, constraints, replication and memory limits.
• AI 35Rate limits, context windows, GPU memory and model-serving failures.
• Network 35Refused connections, timeouts, resets, MTU problems and port exhaustion.
• Kubernetes 34CrashLoopBackOff, ImagePullBackOff, OOMKilled, RBAC, scheduling and storage.
• Docker 27Daemon connectivity, disk space, image pulls, ports and architecture mismatches.
• System 26Disk space, systemd units, file descriptors, OOM killer and scheduled jobs.
• Cloud 25IAM permissions, quotas, service limits and credential failures.
• Security 25JWT validation, CSRF, OAuth grants, SELinux, SSH host keys and CSP.
• TLS 24Untrusted authorities, expiry, hostname mismatch, chains and cipher negotiation.
• Frontend 23Hydration mismatches, bundler resolution, layout shift and font loading.

Something missing or wrong?

This entry is maintained by hand. If the fix is out of date, incomplete, or you have a better one, email a correction and it will be reviewed.