Many Recoll format handlers are written in Python. A few of these depend on modules that can be installed from PyPI, but are not commonly packaged by Linux distributions. Installing these modules system-wide may trigger warnings or cause conflicts.
To address this, the pyvirtualenv configuration parameter was
introduces in Recoll 1.44.3. It allows Recoll to easily run within a Python virtual environment,
keeping its required modules mostly isolated from system packages, and personal user modules
under ~/.local/lib.
Note that this parameter simply sets the VIRTUAL_ENV environment variable
and adjusts the PATH. You can achieve the same result manually by exporting
these variables before running Recoll processes (recoll,
recollindex, recollq).
The Python version inside by the virtual environment must match the system's Python, as some modules installed by Recoll itself, such as the Python extension, will be shared: copied or linked from the system.
Below is a step-by-step example of setting up a virtual environment for all
Python modules currently used by by Recoll. This scenario was
created on Debian Trixie, and you will need to adjust a few packaging commands and package
names (used in addition to pip3) for other distributions. In this example,
the virtual environment is placed in ~/recollpy, which would also be the
setting of pyvirtualenv.
Creating the virtual environment: As per usual:
cd python3 -m venv recollpy source recollpy/bin/activate
All the following takes place inside the virtual environment.
CHM: this needs chmlib and the
pychm extension which is packaged as recollchm by
Recoll because of issues with the upstream.
sudo apt install libchm1 cd ~/recollpy/lib/python3.13/site-packages ln -s /usr/lib/python3/dist-packages/recollchm
Audio:
pip3 install mutagen
7zip: This is a binary extension, you need gcc and the Python development files, and also a specific version of the extension.
sudo apt install gcc libpython3-dev pip3 install py7zr==0.22
RAR archives: You need to add the nonfree repository to the
apt sources.list because of licensing issues with
libunrar. Then:
sudo apt update sudo apt install libunrar5t64 pip3 install unrar
Chinese language support:
pip3 install jieba
Korean language support: This is broken at the moment, the python-mecab-ko installation fails, I need to look into it.
pip3 install python-mecab-ko
Korean HWP office files:
pip3 install six pyhwp
kar files:
pip3 install chardet
jupyter notebooks:
pip3 install jupyter
Joplin: This needs the Recoll Python extension. We link it from the system.
cd ~/recollpy/lib/python3.13/site-packages ln -s /usr/lib/python3/dist-packages/recoll
PDF XMP support: This needs lxml and the GObject introspection library module which is difficult to build (in my experience). We link it from the system.
pip3 install lxml cd ~/recollpy/lib/python3.13/site-packages ln -s /usr/lib/python3/dist-packages/gi
