Fix it fast
Most likely: pip could not download a compatible wheel, so it tried to build one from source and the wheel build failed.
1. Confirm this is your error
ERROR: Failed to build installable wheels for some pyproject.toml based projects (tiktoken)
ERROR: Could not build wheels for _ which use PEP 517 and cannot be installed directly2. Check the cause
python -m pip install -v <package>
python -m pip debug --verbose
python -c 'import sys, platform; print(sys.version); print(platform.platform())'3. Apply the safe fix
# Update build tooling, then retry with a clean download/build.
python -m pip install --upgrade pip setuptools wheel
python -m pip install --no-cache-dir -v <package>
# If possible, use a Python/package version that has a prebuilt wheel for your platform.
python -m pip install "<package>==<version-with-wheel>"4. Verify it works
python -m pip install <package>
python -c 'import <module>; print("ok")'Don't use unsafe shortcuts
- Do not ignore the earlier compiler or linker error, that is the real build failure.
- Do not keep retrying the same source build without installing the missing toolchain or switching to a wheel.
- Do not rely on old pip when newer pip may select a compatible wheel tag.
What Broke in the Build
pip attempted to build a wheel from a PEP 517 project, but the wheel build failed and pip cannot install it without a wheel.
Find the first real build failure
Install build dependencies (compiler + headers) for your OS.
Upgrade pip/build tooling and retry with --no-cache-dir -v.
If possible, install a version of the package that has a wheel for your platform, or use a Python version that the package supports with wheels.
If the package requires Rust, install Rust (via rustup on most platforms) and retry.
Find the first real build error
Re-run with -v and capture logs. Identify the first toolchain/library error.
Confirm your OS has a compiler toolchain installed and Python development headers available.
Check whether a prebuilt wheel exists for your Python version, if not, consider using a supported Python version.
Why the Build Fails
Usually this comes down to no compatible wheel exists, so pip must build from source, your environment lacks a required build toolchain (C/C++ compiler, Rust, etc.), your environment lacks required system libraries/headers used by the extension module, or the package's build scripts or backend are incompatible with your Python/platform.
Prove the Build Path Is Clean
Re-run the install and confirm a wheel is built (or downloaded) and installed successfully, and confirm import/runtime works with python -c 'import <module>'.
Where the real build failure usually starts
This is the part worth understanding if the quick fix did not hold. It explains what pip is trying to do at the moment the error appears.
For PEP 517/518 projects, pip builds a wheel using the project's declared build backend.
If the wheel build fails, pip cannot proceed with installation because it doesn't fall back to legacy setup.py install for those projects.
The detailed failure is above the summary:compiler errors, missing toolchains (C/C++/Rust), or missing system libraries are the most common causes.
Keep Build Prerequisites Consistent
To prevent this, use base images/CI runners with build toolchains preinstalled when you expect source builds, prefer wheels or internal wheel caches to avoid rebuilding from source repeatedly, and stay on supported Python versions for your dependency stack.
Docs and source code
github.com/pypa/pip/blob/25.3/src/pip/_internal/exceptions.py
pip raises this diagnostic when a PEP 517 wheel build fails, the real cause is in the earlier build output from the backend/toolchain. - GitHub
class InstallWheelBuildError(DiagnosticPipError):
reference = "failed-wheel-build-for-install"
def __init__(self, failed: list[InstallRequirement]) -> None:
super().__init__(
message=(
"Failed to build installable wheels for some "
"pyproject.toml based projects"
),
context=", ".join(r.name for r in failed), # type: ignore
hint_stmt=None,
)