pyenv install stops with BUILD FAILED while compiling Python
BUILD FAILEDShort 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.
Fix it fast
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 52Match what you see, then jump to its fix
- 1
The 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
The 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
Resource temporarily unavailable in the build logThe build runs out of resourcesFix - 4
bad interpreter: Permission denied/tmp is mounted noexecFix - 5
The 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
- 1
What does the error look like?
BUILD FAILEDThe Python zlib extension was not compiled. Missing the zlib?The Python ssl extension was not compiled. Missing the OpenSSL lib?Resource temporarily unavailablebad 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 python33Verify
Run the install again. The build finishes without the missing-extension notice.
pyenv install 3.12.1
pyenv versionsConfirmed by github.com
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 302Fix
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.13Verify
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
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 -m2Fix
Build with one job.
MAKE_OPTS='-j 1' pyenv install 3.12.13Verify
The build runs to the end.
pyenv versionsConfirmed by github.com
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 /tmp2Fix
Point TMPDIR at a directory you own that allows execution.
mkdir -p "$HOME/src"
TMPDIR="$HOME/src" pyenv install 3.12.13Verify
The install finishes and the version appears in pyenv versions.
pyenv versionsConfirmed by github.com
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 version2Fix
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.13Verify
Import ssl from the new interpreter.
pyenv shell 3.12.1
python -c "import ssl; print(ssl.OPENSSL_VERSION)"Confirmed by github.com
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:
- stegnor.comMy company site: 804 pages from a Python and Jinja generator, with 15 free browser tools.
- MenuloA restaurant discovery platform in Germany, kept current by a Python ingestion pipeline.
- ShopGoAn e-commerce aggregator with a Python scraping engine behind its catalog, past 10K Google Play downloads.
Related fixes
Servers
pyenv is installed but the shell cannot find it
pyenv: command not found
The shell finds pyenv only if its bin folder is on PATH.
3 causes, each with a fixServers
pip install confluent-kafka fails because librdkafka/rdkafka.h is missing
pip stops while building confluent-kafka from source
The error means pip is compiling confluent-kafka from source, and the compiler cannot find the librdkafka C headers.
3 causes, each with a fixServers
cv2.imshow raises 'not implemented' because the wrong OpenCV package is installed
cv2.imshow() works in one environment and fails in another
The headless OpenCV packages are built without any GUI code, so cv2.imshow cannot open a window.
2 causes, each with a fixServers
pip install Cython succeeded, but the shell cannot find cythonize
a pip warning that a script was installed to a directory outside PATH
pip put the cythonize script in a folder your shell does not search.
3 causes, each with a fixServers
Django returns a 500 behind Gunicorn and the traceback is nowhere
The traceback shows locally with runserver but not under Gunicorn
With DEBUG set to False, Django's default logging does not print errors to the console.
2 causes, each with a fixServers
Docker build fails with apk: not found in a Python or Ubuntu image
/bin/sh: 1: apk: not found
apk is the package manager of Alpine Linux only.
2 causes, each with a fix