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

URL: https://antideploy.com/blog/failed-building-wheel

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

**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
```

## At a glance

- **What it means**: A compile step failed
- **Fix one**: Use a prebuilt wheel
- **Fix two**: Pin Python to 3.12
- **Fix three**: A Dockerfile for system libraries

Published 7 October 2026. Facts checked 7 October 2026. 1 min read.

## 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](https://antideploy.com/blog/how-to-deploy-a-docker-app-with-your-own-dockerfile).

**requirements.txt**

```
psycopg[binary]
```

## Wheel questions, answered.

Anything else? Write to us and a person answers.

[support@antideploy.com](mailto: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.

## 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](https://antideploy.com/platform), or [all the guides](https://antideploy.com/blog).

- [ERROR: Could not find a version that satisfies the requirement](https://antideploy.com/blog/could-not-find-a-version-that-satisfies-the-requirement): No version matches your requirements.txt, often because of the Python version. Pin Python or loosen the pin.
- [invalid Python version specified: failed to resolve version](https://antideploy.com/blog/python-version-not-available): The builder does not offer the Python version you asked for. Pin one of the versions it lists.
- [How to deploy a Docker app with your own Dockerfile](https://antideploy.com/blog/how-to-deploy-a-docker-app-with-your-own-dockerfile): Where the Dockerfile must be, how the port is read, the account rule and the RUN --mount limit.

- [Deployments](https://antideploy.com/platform/deployments)
- [Logs and monitoring](https://antideploy.com/platform/logs-and-monitoring)
- [Hosting](https://antideploy.com/platform/hosting)

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.

To set this up, give your coding agent this sentence:

```text
Set this project up to deploy on Antideploy. Fetch https://antideploy.com/agent.md and follow it.
```