last updated: 2026-11-11
My software to create static homepages from markdown files called PYSHPCREATOR (PYthon Simple HomePage CREATOR) did not run with newer Python versions because of some older libraries.
A virtual environment helps with such problems, because it isolates the project from other environments, including the global interpreter environment. So no more complications from conflicting package versions, and the possibility to use an older python version. More in the python docs: https://docs.python.org/3/library/venv.html.
One remark before we start. The generic python command historically referred to Python 2 and so we get an error on new Ubuntu/Debian systems because we should use python3. we could avoid this problem by installing a package with:
sudo apt install python-is-python3
but I will stick with python3.
When we use a Linux computer with an installed Python (e.g., (K)ubuntu), or when we install Python, a directory is created which contains the Python interpreter and some other directories and files associated with it. We should check the Python version and the paths with the following commands:
python3 --version
whereis python3

In /usr/bin we find a symlink python3 that points to the Python interpreter python3.14 in the same directory (pip3 is also in this directory). In /usr/lib/python3 and /usr/lib/python3.14 we find the other files.
The Python interpreter identifies its home directory (the sys.prefix) within the filesystem. Based on that location, it automatically constructs a search path (sys.path) to find all the files and libraries it needs to run.
A virtual environment (venv) is a copy of that directory structure, containing a link to the Python interpreter and its own separate bin and lib directories, a special pyvenv.cfg file that affects startup of the interpreter, and some third-party Python packages. Python packages installed with pip3 into a virtual environment will not interfere with other Python applications on the same system. When you use a virtual environment, the presence of the pyvenv.cfg file tells the interpreter to redefine its sys.prefix. This redirects the sys.path to point toward your local bin and lib folders instead of the system-wide ones.
When we activate the venv, some environment variables are temporarily set so the commands python3 or pip3 or other commands look for them in the venv's directories.
When we deactivate the venv, we return those environment variables back to their old values.
So a virtual environment is a (sometimes hidden) directory which contains a Python file structure for a specific Python version, and also stores libraries downloaded through pip. The virtual environment works by manipulating the PATH environment variable so that the correct python interpreter is executed.
Let's create a virtual environment in our software folder (e.g. pyshpcreator/Python) It is good to install the virtual environment in a separate folder (e.g. .venv)), so it can be excluded if versioning with e.g. git.
cd ~/pyshpcreator/Python
python -m venv .venv
In the bin directory in the .venv folder I see that python 3.12 was used and pip is there to install further packages.
To work in our virtual environment, we have to activate it:
cd ~/pyshpcreator/Python
source .venv/bin/activate
Now we remark the following prefix before our promt: (.venv).
Now we can install our missing modules (e.g. markdown2, pygments) with pip:
pip install markdown2 pygments
After installing all the modules we can check the requirement (all the modules) with the following command:
python3 -m pip freeze
Here we see the output for my PYSHPCREATOR software:
bcrypt==4.2.1
beautifulsoup4==4.12.3
bs4==0.0.2
certifi==2025.1.31
cffi==1.17.1
charset-normalizer==3.4.1
cryptography==44.0.0
idna==3.10
markdown2==2.5.2
paramiko==3.5.0
pycparser==2.22
Pygments==2.19.1
PyNaCl==1.5.0
requests==2.32.3
soupsieve==2.6
urllib3==2.3.0
Or better we can create a file called requirements.txt containing all the requirements:
pip3 freeze > requirements.txt
If a requirements.txt file is given by the maintainer of the software, it is easy to recreate the modules in a new virtual environment. When you create the virtual environment, you need to use the same python version than the maintainer, otherwise it is possible that module versions will not fit!
First download the repo from github, create and activate the virtual environment:
cd ~
git clone https://github.com/weigu1/pyshpcreator.git
cd pyshpcreator/Python
python -m venv .venv
source .venv/bin/activate
Now we can install all the dependencies with:
python3 -m pip install -r requirements.txt
Finally we open the program withNow we can open the program with:
python pyshpcreator.py
We leave with:
deactivate
When I updated my computer with a new Kubuntu version, my old environment did not work anymore due to incompatible python versions. I got this error:
Could not find platform independent libraries <prefix>
Could not find platform dependent libraries <exec_prefix>
Fatal Python error: Failed to import encodings module
Python runtime state: core initialized
ModuleNotFoundError: No module named 'encodings'
So first I deleted the od .venv folder and created a new environment and entered it:
python3 -m venv .venv
source .venv/bin/activate
I tried to reinstall all the modules with pip:
python3 -m pip install -r requirements.txt
This gave me an error with the cffi module. Removing the line with cffi from requirements.txt did the trick.
A check with python3 -m pip freeze showed that cffi was installed with a newer version.
So I checked the other modules with:
pip list --outdated
Here the result:
Package Version Latest Type
------------------ --------- --------- -----
bcrypt 4.2.1 5.0.0 wheel
beautifulsoup4 4.12.3 4.15.0 wheel
certifi 2025.1.31 2026.6.17 wheel
charset-normalizer 3.4.1 3.4.9 wheel
cryptography 44.0.0 49.0.0 wheel
idna 3.10 3.18 wheel
markdown2 2.5.2 2.5.5 wheel
paramiko 3.5.0 5.0.0 wheel
pip 25.1.1 26.1.2 wheel
pycparser 2.22 3.0 wheel
Pygments 2.19.1 2.20.0 wheel
PyNaCl 1.5.0 1.6.2 wheel
requests 2.32.3 2.34.2 wheel
soupsieve 2.6 2.9 wheel
urllib3 2.3.0 2.7.0 wheel
The simplest way to update all these packages in one go was to install pip-review, a helper for Python's pip package installer.
We can update everything in one go with the auto parameter.
pip install pip-review
pip-review --auto
If you want to or need to use a different python version you have to install it first on your linux system and use then the right command (e.g. python3.9):
sudo apt install python3.9
mkdir /savit/programming/python/test
python3.9 -m venv /savit/programming/python/test