Python "Could not find a version that satisfies" Error: Diagnosing and Fixing It by Cause in pip and Poetry

Python "Could not find a version that satisfies the requirement": Diagnosing and Fixing It by Cause (pip, Poetry)

If pip install printed something like this, start by understanding exactly what the error means.

ERROR: Could not find a version that satisfies the requirement foo==2.0 (from versions: 1.0, 1.1)
ERROR: No matching distribution found for foo==2.0

It means pip could not find a single installable file (wheel or source distribution) on the index it is looking at that matches the requested name, the version specifier, your current Python version, and your current platform. Despite how it sounds, it is usually not a conflict between packages. A real conflict shows up as a different error, ResolutionImpossible (section 4).

So the fix is to find out which condition left pip with zero candidates. In practice the cause is almost always one of these:

• A typo in the package name, or an import name that differs from the distribution name
• Your Python version is outside the range that package version supports (Requires-Python)
• There is no wheel for your OS, CPU architecture, or Python version
• A private index, proxy, or SSL problem keeps pip from seeing the index you expect
• pip is so old that it doesn't recognize newer wheel formats

1. The first clue in the message: (from versions: ...)

The list in parentheses tells you where to look.

• (from versions: none) → pip found no usable files at all. The name is wrong, the package isn't on that index, the connection to the index failed, or there is no file for your Python and platform.
• A version list appears, but not the version you asked for → the requested version doesn't exist (for example 2.0, not 2.0.0), or it exists but was dropped from the candidates because it doesn't fit your Python version or platform.

2. 30-second diagnostic commands

python -V                      # the Python version you are using
python -m pip --version        # which Python this pip belongs to, and the pip version
python -m pip index versions <package>          # versions visible on the index (pip 21.2+, experimental)
python -m pip install -v "<package>==<version>" # which index was used and why each file was skipped
python -m pip download --only-binary=:all: --no-deps "<package>==<version>"  # is there a wheel for this environment?
python -m pip config list      # check index-url, extra-index-url, proxy, only-binary settings

Using python -m pip instead of pip avoids the "pip belongs to 3.8 but python is 3.12" mix-up. In the -v output, check whether files were skipped because they "require a different Python" or because the "wheel tags are not compatible". That reason is your cause.

3. Fixes by cause

If only-binary is set in a config file or environment variable, a package that only ships a source distribution also produces this error. Check pip config list and env | grep -i pip together.

If you mix a private index with PyPI through extra-index-url, pip may install the wrong one when the same name exists on both (a dependency confusion attack). Serving internal packages through a single private index that proxies PyPI is the safer setup.

4. A real dependency conflict shows up as ResolutionImpossible

Since pip 20.3 the backtracking resolver is the default, so when packages require versions that don't overlap, pip detects the conflict during installation and reports it like this.

ERROR: Cannot install package-a==1.0 and package-b==2.0 because these package versions have conflicting dependencies.
ERROR: ResolutionImpossible: for help visit https://pip.pypa.io/en/latest/topics/dependency-resolution/#dealing-with-dependency-conflicts

That case has different causes and a different fix order; see Fixing the pip ResolutionImpossible dependency conflict error. To inspect the dependencies of an environment that is already installed, pipdeptree helps.

python -m pip install pipdeptree
pipdeptree                 # dependency tree of installed packages
pipdeptree -r -p requests  # reverse: who depends on requests
python -m pip check        # check for version mismatches among installed packages

In Poetry, the same situations use different wording. Because myproject depends on foo (2.0) which doesn't match any versions, version solving failed. is the same "no candidates" problem as ①–⑤ above. The current project's supported Python range (...) is not compatible with some of the required packages Python requirement means the Python range in pyproject.toml is wider than what the package supports; narrow the project's Python range to match the package's requirement.

5. Preventing it: virtual environments and pinned versions

A separate virtual environment per project keeps other projects and system packages out of the way. venv has been in the standard library since Python 3.3.

python3 -m venv .venv
source .venv/bin/activate          # macOS/Linux
# .venv\Scripts\activate           # Windows (Command Prompt)
# .\.venv\Scripts\Activate.ps1     # Windows (PowerShell)
python -m pip install -r requirements.txt
deactivate                         # when you are done

Pick a pinning approach that fits the size of the project.

A lock file pins package versions but not the Python version or platform. If this error appears only in CI or Docker while it works locally, start by matching python -V and the base image (Alpine or not) on both sides.

When the environment seems broken: recreate the virtual environment

deactivate                  # if it is active
rm -rf .venv                # delete the virtual environment (run inside the project folder)
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt   # or: poetry install

References: official docs

• pip: Dependency Resolution
• pip index
• Python Packaging: Platform compatibility tags
• Python docs: venv
• Poetry: Basic usage

FAQ

Q. What should I check first when I see (from versions: none)? A. Check, in order, that the package (distribution) name is right, that python -m pip install -v actually reached the index, and that there is a file for your Python version and platform. Suspect a dependency conflict only after that.

Q. It installs locally but fails only in Docker or CI. A. Usually the Python version or the platform differs. Check that python -V in CI matches your local one, and whether the base image is Alpine (musl) with no wheel available. It is also common for a corporate proxy or private index setting to be missing only in CI.

Q. Should I commit poetry.lock to Git? A. For an application, yes; your teammates and CI will install the same set of versions. The lock file doesn't pin the Python version, though, so also keep the Python range in pyproject.toml and the Python version in CI aligned.