Antideploy

BlogPython

ERROR: Failed building wheel for psycopg2 How to fix it.

A Python package had to be compiled from source, and the compile failed. A version with a prebuilt wheel usually fixes it.

How the Agent API works
What you see
Building wheel for psycopg2 (setup.py): finished with status 'error'
ERROR: Failed building wheel for psycopg2
ERROR: Could not build wheels for psycopg2, which is required to install
pyproject.toml-based projects
  • What it meansA compile step failed
  • Fix oneUse a prebuilt wheel
  • Fix twoPin Python to 3.12
  • Fix threeA Dockerfile for system libraries

What it means

Most Python packages come as a ready-made file called a wheel. When no wheel fits your Python version and system, pip tries to compile the package from source, and that needs compilers and system libraries. Here the compile failed. The package named in the message is the one that failed.

How to fix it

  1. Use a version with a prebuilt wheel

    For Postgres, use psycopg2-binary, or psycopg[binary], instead of psycopg2. The binary versions include what they need.

  2. Pin a Python version that has wheels

    Packages publish wheels for new Python releases some time after they ship. Pin an older version in .python-version, for example 3.12, and deploy again.

  3. If it needs system libraries, use a Dockerfile

    Some packages need a system library that the standard build image does not have. A Dockerfile can install it. See how to deploy with your own Dockerfile.

requirements.txt
psycopg[binary]

01Questions

Wheel questions, answered.

Anything else? Write to us and a person answers.

support@antideploy.com
Why does it install on my machine?

Your machine may already have the compiler and libraries, or a wheel exists for the Python version you use there.

Is psycopg2-binary fine for production?

It works for most apps. Its maintainers suggest building from source for large deployments, but for a small app the binary version is the practical choice.

Does this failed deploy cost anything?

No. Failed deploys never count against your plan.

+Keep reading

More guides, and the platform.

Each platform page covers one part of Antideploy: what it does, where it stops and the questions people ask. See the whole platform, or all the guides.

Facts on this page were checked against the live platform on 7 October 2026.

Deploy something. Start with one sentence.

Paste one sentence into your coding agent, click Approve once, and get a live link. No card, no trial clock.

Start from GitHub or a folder
Prompt copied Paste it into Claude Code, Codex or Cursor and press Enter.