PLIP profiles non-covalent protein-ligand interactions from PDB files

From a PDB file to a list of named interactions

PLIP, the Protein-Ligand Interaction Profiler, does one thing: it reads a three dimensional structure and reports how the ligand in it is held by the protein. The interactions it detects are non-covalent ones, and it names them by type rather than leaving you to read a distance table, so the output is a list of hydrophobic contacts, hydrogen bonds, pi-stacking and the rest, each attached to a specific residue.

The project describes itself as fully automated, and the method follows a published protocol, with the repository pointing at Schake, Bolz and colleagues from 2025 and the DOI 10.1093/nar/gkaf361. That matters for a tool in structural biology, where the difference between an interaction definition that matches the literature and one that does not decides whether the result is usable.

The implementation is Python, and the packaging is modern even though the code is not new. The project metadata declares `requires-python` of 3.6 or above, with the runtime dependencies limited to `numpy` at 1.13.3 or newer, `lxml` at 4.2.1 or newer and `openbabel` at 3.2.0 or newer. The version number is not written in the metadata but read from the code itself, through the `plip.basic.config.__version__` attribute, and a console script named `plip` is installed.

The organisation behind it is PharmAI GmbH, listed as both author and maintainer, and the licence is GPL-2.0, spelled GPL-2.0-only in the package metadata. The project is classified as Production/Stable and aimed at the science and research audience.

Five delivery routes, each with a different best fit

The project publishes the same analysis through five routes, and the table that maps use cases onto them is the most useful part of the documentation. The routes are a web server, Docker, Singularity, the Python module and a Google Colab notebook.

The web server is the one-click option for a single complex. Docker is the everyday choice for a local analysis and for building a workflow around the command line. Singularity is the route aimed at high performance computing environments, where the container runtime already exists and Docker does not, and the documentation notes that Singularity makes PLIP easy to use in HPC settings. The Python module is for people who want to call PLIP from their own code, and the Colab notebook removes the need to install anything locally, with no constraints on PDB file and protein sizes.

The table is also candid about where each route falls short. For analysing a single complex, the web server, Docker and Colab all work, while Singularity is marked as a partial fit and the Python module is marked as not suitable. For large complexes, the web server is ruled out, and for a Python programmer who wants to embed PLIP, only the Python module is a full fit. For very large batch work, the web server and the Colab notebook are ruled out entirely, and the Python module is only a partial fit, leaving Singularity as the route built for it.

That matrix is worth reading twice, because it is a summary of where PLIP has been optimised and where it has not.

Docker is the shortest path, and the image runs the tests at build time

If Docker is installed, the documented one-liner analyses a structure and mounts the current directory for the results:

$ docker run --rm \
    -v ${PWD}:/results \
    -w /results \
    -u $(id -u ${USER}):$(id -g ${USER}) \
    pharmai/plip:latest -i 1vsn -yv

The user id mapping is not decoration, it is there so the files written into the mounted directory belong to you rather than to root. The image tag is `latest`, and the container is built for multiple architectures, amd64 and ARM, so one command works on an Apple Silicon laptop and on a cluster node.

The `Dockerfile` is worth reading because it shows what the image contains. It starts from `debian:stable`, installs `pymol`, `python3-lxml`, `python3-openbabel` and `python3-pymol`, copies the `plip/` source tree in, sets `PYTHONPATH` to the source directory, and sets the entry point to `python3 /src/plip/plipcmd.py`. There is also a `Dockerfile.20.04` for the older base, and a `build_multi.sh` script for building the multi-architecture image.

One detail stands out. The image build runs the test suite: it changes into `/src/plip/test`, makes `run_all_tests.sh` executable and executes it before the image is finished. So an image that builds has already run the tests inside the build.

For Singularity users the equivalent is a single pre-built image file from the project's releases, run as `./plip.simg -i 1vsn -yv`, with the caveat that Singularity has to be installed on the base system first.

The Python module works per binding site, not per file

When you call PLIP from Python, the unit of analysis is the binding site rather than the file. A complex is loaded into a `PDBComplex`, the object lists its binding sites, and each site gets its own interaction set once `analyze()` has run:

from plip.structure.preparation import PDBComplex

my_mol = PDBComplex()
my_mol.load_pdb('/tmp/1EVE.pdb') # Load the PDB file into PLIP class
print(my_mol) # Shows name of structure and ligand binding sites
my_bsid = 'E20:A:2001' # Unique binding site identifier (HetID:Chain:Position)
my_mol.analyze()
my_interactions = my_mol.interaction_sets[my_bsid] # Contains all interaction data

# Now print numbers of all residues taking part in pi-stacking
print([pistack.resnr for pistack in my_interactions.pistacking]) # Prints [84, 129]

Two things follow from that snippet. First, the identifier for a binding site is a compound key of het id, chain and position, so a complex with several ligands is addressed site by site. Second, the interactions arrive grouped by type on the set object, and each entry carries the residue number, which is what you want when you are building a table of contacts rather than a picture.

The command line tool exposes the same analysis for people who do not want to write Python. The `plipcmd.py` script detects, reports and visualises interactions, and the documented example creates a PyMOL visualisation for the inhibitor NFT and its target protein in the structure 1vsn:

# Set an alias to make your life easier and create and enter /tmp/1vsn
$ alias plip='python ~/plip/plip/plipcmd.py'
$ mkdir /tmp/1vsn && cd /tmp/1vsn
# Run PLIP for 1vsn and open the resulting visualization in PyMOL
$ plip -i 1vsn -yv
$ pymol 1VSN_NFT_A_283.pse

The output formats are several: rendered images, PyMOL session files, human-readable text files and XML files, so the same run can feed a figure, a PyMOL session and a downstream parser.

OpenBabel does the chemistry, PyMOL does the picture

The dependency list explains most of PLIP's behaviour. Python 3.6.9 or newer is the floor. OpenBabel 3.0.0 or newer with its Python bindings is required, and the documentation is unusually direct about the difficulty here, noting that many users have trouble setting up OpenBabel with Python bindings correctly and providing installation help for it in a dedicated section. PyMOL 2.3.0 or newer with Python bindings is optional and needed for visualisation only, and ImageMagick 7.0 or newer is optional as well.

The split explains the two failure modes you will meet. Without a correctly wired OpenBabel, the analysis itself is in trouble, because that is the library doing the chemical perception of the ligand and the interactions. Without PyMOL, the analysis still runs and you simply lose the rendered image and the session file.

The dependency on OpenBabel is also why the containers are the recommended install. The Dockerfile pulls in `python3-openbabel` and `python3-pymol` from Debian packages, so the pairing that is hard to arrange by hand is already correct in the image.

If you do want to run from source, the documented path is to clone the repository and either set `PYTHONPATH` to the root of the checkout or run the setup script in it. A `pip install plip` from PyPI is also supported, with the explicit warning that the dependencies above still have to be installed and linked correctly.

Where PLIP is the wrong tool

The clearest limit is scale. The delivery table says plainly that a Python programmer gets a partial fit for very large batch work, and that the web server and the Colab notebook do not cover that case at all. PLIP is a profiler for complexes, not a pipeline for screening a library of millions of structures, and the Singularity route is the one aimed at that.

The second limit is that it profiles one complex at a time in the way the documentation describes, and the analysis is defined by the interaction types PLIP implements. If your question needs an interaction category that is not in the output, there is no configuration for it. The published method fixes the definitions, which is what makes the results citable and also what makes them narrow.

The third is the dependency surface. A tool that needs OpenBabel wired up correctly, and optionally PyMOL and ImageMagick, has more ways to fail on a fresh machine than a pure Python package. That is the argument for the container image, and it is also the argument for a different kind of tool if your requirement is a self-contained library with no native chemistry dependency at all.

One more constraint to know about: the container images are the maintained distribution route, and if you install from PyPI you inherit the dependency burden instead. The project also notes that on systems where Python 3 is executed as `python3`, the `python` and `pip` commands in the instructions should be replaced accordingly, which is the kind of small thing that wastes an afternoon when it goes wrong.

Editorial conclusion

PLIP fits a structural biologist or computational chemist who needs a standard, scriptable account of how a ligand sits in its binding site, whether through the command line in a workflow, the Python module inside an existing pipeline, or the web server for a one-off look. It does not fit a whole-proteome project, since the delivery table is explicit that only the Singularity route is aimed at very large batch runs, and the Python module is the weakest option for large complexes. Check three things first: that your Python is 3.6.9 or newer, that OpenBabel 3.0.0 with Python bindings is correctly installed, which the project says many users get wrong, and which version you pin, since v3.0.1 was released on 2026-07-03 and the last push was on the same day.

Frequently asked questions

Official sources

1. License: GPL-2.0
2. pharmai/plip on GitHub
3. Project website
4. README
5. Releases