Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

pyenv install stops with BUILD FAILED while compiling Python

ErrorBUILD FAILED

Short answer

pyenv compiles Python from source, so BUILD FAILED almost always means a missing C library or a limit on the machine. The message prints a log path: open it and read the first error, not the last. Install the Ubuntu build dependencies, then retry; if the log shows resource or permission errors, change the job count or TMPDIR.

  • Applies to pyenv 2.x, Ubuntu 24.04, Python 3.12 and 3.13 builds
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    BUILD FAILED prints the path of a log file. Open it, search for the word error, and start with the earliest match; the rest is usually fallout.

    grep -n -i "error" /path/printed/after/BUILD-FAILED.log | head -n 5
  2. 2Match what you see, then jump to its fix

    1. 1The Python zlib extension was not compiled, or the ssl extension was not compiled, or a missing header (.h) in the logBuild dependencies are not installedFix
    2. 2The build ends with: The necessary bits to build these optional modules were not foundOptional modules are skipped and the build looks like it failedFix
    3. 3Resource temporarily unavailable in the build logThe build runs out of resourcesFix
    4. 4bad interpreter: Permission denied/tmp is mounted noexecFix
    5. 5The Python ssl extension was not compiled. Missing the OpenSSL lib?OpenSSL is not found in a non-standard place, or is too new for an old PythonFix

What does the error look like?

  • BUILD FAILED
  • The Python zlib extension was not compiled. Missing the zlib?
  • The Python ssl extension was not compiled. Missing the OpenSSL lib?
  • Resource temporarily unavailable
  • bad interpreter: Permission denied

Cause 1 of 5

Build dependencies are not installed

1Check

A fresh Ubuntu, a container or WSL image has no C compiler or -dev libraries. Ubuntu Server may not even have make.

gcc --version | head -n 1
dpkg -s zlib1g-dev libssl-dev libbz2-dev libsqlite3-dev 2>&1 | grep -E "Status|not installed"

2Fix

Install the build dependencies. The pyenv wiki names zlib, OpenSSL, bz2 and sqlite headers; the CPython developer guide gives the complete route, apt-get build-dep (it needs deb-src sources enabled first).

sudo apt-get update
sudo apt-get install make build-essential zlib1g zlib1g-dev libssl-dev libbz2-dev libsqlite3-dev
# complete set, after enabling deb-src in your apt sources:
# sudo apt-get build-dep python3

3Verify

Run the install again. The build finishes without the missing-extension notice.

pyenv install 3.12.1
pyenv versions

Confirmed by github.com

Did this fix it?

Cause 2 of 5

Optional modules are skipped and the build looks like it failed

1Check

CPython lists the extension modules it could not build because a library was absent, and points you to configure.ac and config.log. The list names what to install (for example gdbm, readline, tk, lzma).

pyenv install 3.12.1 2>&1 | tail -n 30

2Fix

Install the matching -dev packages for the modules you need, then rebuild. The developer guide lists them (for example libbz2-dev, libffi-dev, libgdbm-dev, liblzma-dev, libsqlite3-dev, libssl-dev, tk-dev, uuid-dev and zlib1g-dev). Re-running the build is required, since modules are only detected at configure time.

sudo apt-get install libffi-dev libgdbm-dev liblzma-dev tk-dev uuid-dev
pyenv install 3.12.1

3Verify

Import the standard-library modules you needed from the new interpreter.

pyenv shell 3.12.1
python -c "import ssl, zlib, bz2, sqlite3, lzma; print('ok')"

Confirmed by devguide.python.org

Did this fix it?

Cause 3 of 5

The build runs out of resources

1Check

A small VM, container or WSL instance with low limits can fail when make runs many parallel jobs.

nproc
free -m

2Fix

Build with one job.

MAKE_OPTS='-j 1' pyenv install 3.12.1

3Verify

The build runs to the end.

pyenv versions

Confirmed by github.com

Did this fix it?

Cause 4 of 5

/tmp is mounted noexec

1Check

The pyenv wiki says this error usually means /tmp is mounted noexec, which stops programs built there from running.

findmnt -no OPTIONS /tmp

2Fix

Point TMPDIR at a directory you own that allows execution.

mkdir -p "$HOME/src"
TMPDIR="$HOME/src" pyenv install 3.12.1

3Verify

The install finishes and the version appears in pyenv versions.

pyenv versions

Confirmed by github.com

Did this fix it?

Cause 5 of 5

OpenSSL is not found in a non-standard place, or is too new for an old Python

1Check

Find where OpenSSL lives. Older CPython releases need OpenSSL 1.0 while current systems ship a newer one, so a very old Python version may not build against the OpenSSL your system ships.

openssl version -d
openssl version

2Fix

Install libssl-dev. For a custom OpenSSL, tell the build where it is. If you need an old Python on a new system, pick a newer patch release of that minor version instead.

sudo apt-get install libssl-dev
CONFIGURE_OPTS="--with-openssl=/path/to/openssl" pyenv install 3.12.1

3Verify

Import ssl from the new interpreter.

pyenv shell 3.12.1
python -c "import ssl; print(ssl.OPENSSL_VERSION)"

Confirmed by github.com

Did this fix it?

How do I stop it coming back?

  • Put the build dependencies into your provisioning script, Dockerfile or WSL setup so the first pyenv install works.
  • Always read the build log from the top; fix the first error and ignore later ones.
  • Pin one Python version in your project so every machine builds the same release.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.