Troubleshooting

This page lists common issues encountered when installing or running Shrinkwrap and how to resolve them.

pip installs but `shrinkwrap` command not found

Ensure that:

A virtual environment is activated

Verify:

which python
which pip
which shrinkwrap
pip show shrinkwraptool

If shrinkwrap is not on PATH, reinstall inside the active environment.

Wrong Python version

Shrinkwrap requires Python 3.9.0 or newer.

Check the active Python version:

python -V

If the version is too old, create a new virtual environment using pyenv or venv and reinstall Shrinkwrap.

If the issue persists, reinstall Shrinkwrap:

python -m pip install --force-reinstall shrinkwraptool

pip installs old versions

Force pip to upgrade and ignore cached wheels:

python -m pip install --upgrade --no-cache-dir shrinkwraptool

Editable install not picking up changes

Ensure Shrinkwrap was installed in editable mode:

python -m pip install -e ".[dev]"

Verify the source location:

python -c "import shrinkwrap; print(shrinkwrap.__file__)"

PEP 668: Externally Managed Environment with pyenv

Symptom

pip install fails even inside an activated pyenv virtualenv:

error: externally-managed-environment

The message may reference /usr/share/doc/python**/README.venv.

Cause

The shell is still using the system Python instead of the pyenv virtualenv. On Debian/Ubuntu, the system Python is marked as externally managed (PEP 668), which blocks pip.

Fix

Re-initialize pyenv and re-activate the environment:

export PATH="$HOME/.pyenv/bin:$PATH"
eval "$(pyenv init -)"
eval "$(pyenv virtualenv-init -)"
hash -r
pyenv activate shrinkwrap-env

Verify that which python and which pip point inside ~/.pyenv/versions.

Fallback

Force the correct interpreter:

pyenv exec python -m pip install <package>

pyenv install: missing optional modules (_bz2, _ssl, readline, curses, ctypes)

Symptom

pyenv install <version> fails (or succeeds with warnings) and reports missing modules such as _bz2, _ssl, readline, _curses or _ctypes:

ModuleNotFoundError: No module named '_bz2'
WARNING: The Python bz2 extension was not compiled. Missing the bzip2 lib?
...
ModuleNotFoundError: No module named '_ssl'
ERROR: The Python ssl extension was not compiled. Missing the OpenSSL lib?

Cause

Python was built without required development headers/libraries (bzip2, OpenSSL, readline, ncurses, libffi, zlib, etc.). pyenv compiles Python from source, so it needs these -dev packages installed first.

Fix (Ubuntu/Debian)

Install build dependencies, then reinstall the Python version:

sudo apt update
sudo apt install -y \
  build-essential curl git ca-certificates \
  libssl-dev zlib1g-dev \
  libbz2-dev libreadline-dev libsqlite3-dev \
  libncurses-dev libncursesw5-dev \
  xz-utils tk-dev libffi-dev liblzma-dev \
  uuid-dev

pyenv uninstall -f <version>
pyenv install <version>

Verify

After install, confirm the modules import correctly:

pyenv shell <version>
python -c "import ssl,bz2,readline,curses,ctypes; print('ok')"