Install & Compatibility
Where this runs
tested against v3.5.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.131s · 18.6MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.6s · import 0.121s · 19MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
run_propka
✓ from propka import run
The primary entry point for programmatic execution is often within the `propka.run` module. You'll typically interact with functions like `run_propka`.
propka
✓ import propka
✗ from propka import calculate_pka_values
While `propka` is the package name, direct top-level imports for specific calculation functions are less common. Instead, functions are typically accessed through submodules like `propka.run` or `propka.molecular_container`.
This quickstart demonstrates how to use PROPKA as a Python module to calculate pKa values for a protein structure. It creates a minimal dummy PDB file, runs the `propka.run.run_propka` function, and prints a success message, indicating that detailed results are written to a `.pka` file.
import os
import propka.run
# Example: Create a dummy PDB file for demonstration
# In a real scenario, you would load an existing PDB file.
example_pdb_content = """
ATOM 1 N ALA A 1 0.000 0.000 0.000 1.00 20.00 N
ATOM 2 CA ALA A 1 1.458 0.000 0.000 1.00 20.00 C
ATOM 3 C ALA A 1 2.155 1.234 0.000 1.00 20.00 C
ATOM 4 O ALA A 1 1.614 2.352 0.000 1.00 20.00 O
ATOM 5 CB ALA A 1 2.000 -1.200 0.000 1.00 20.00 C
"""
with open("dummy.pdb", "w") as f:
f.write(example_pdb_content)
# Run PROPKA programmatically
# The output will typically be written to a .pka file
# and potentially to standard output.
try:
# propka.run.run_propka expects a list of filenames
pka_results = propka.run.run_propka(["dummy.pdb"])
# The 'pka_results' object contains detailed pKa information.
# For a simple print of the summary (similar to command line output):
print("\nPROPKA Calculation Summary (dummy.pdb):")
# Note: Accessing results directly from the returned object might require
# traversing its internal structure, e.g., MolecularContainer.
# The exact structure depends on the PROPKA version and options.
# For demonstration, we'll indicate successful execution and refer to the .pka file.
print("Results written to dummy.pka and available in the returned object.")
# You can read the generated .pka file for detailed results
# with open("dummy.pka", "r") as f:
# print(f.read())
except Exception as e:
print(f"An error occurred during PROPKA calculation: {e}")
finally:
# Clean up the dummy PDB file and output if they exist
if os.path.exists("dummy.pdb"):
os.remove("dummy.pdb")
if os.path.exists("dummy.pka"):
os.remove("dummy.pka")
propka --version
Debug
Known issues
breakingPROPKA 3.5.0 dropped support for Python 3.6 and 3.7. Ensure your environment uses Python 3.10 or higher for the latest versions.fixUpgrade your Python interpreter to version 3.10 or newer.
affects: >=3.5.0
breakingVersion 3.4.0 removed the `--generate-propka-input` argument and direct PROPKA input file support. Input should now be provided primarily via PDB files.fixProvide input directly as PDB files instead of using custom PROPKA input formats or the removed argument.
affects: >=3.4.0
breakingThe API for `propka` is still evolving and is not guaranteed to be stable between minor releases (e.g., changes between 3.2 and 3.3). This may require adjustments to programmatic integrations.fixRefer to the latest API documentation and changelog for each minor version update when integrating programmatically. Consider pinning exact minor versions in production if API stability is critical.
affects: All 3.x versions (especially minor releases)
gotchaOlder, separate `propka.py` scripts (e.g., for PyMOL integration) exist and are distinct from the `propka` Python package. Using these older scripts can lead to confusion or incompatibility.fixAlways install `propka` via `pip install propka` and refer to the official documentation (jensengroup/propka on GitHub) for Python module usage to ensure you are using the correct and supported library.
affects: All versions
gotchaThe command-line tool is `propka3`, not `propka`. When running from the command line, use `propka3 FILENAME.pdb` or `python -m propka FILENAME.pdb`.fixUse the `propka3` executable or `python -m propka` for command-line invocation.
affects: All 3.x versions
Errors
Common errors & fixes
Command 'propka' not found, did you mean: Command 'propka3'
Users often try to execute the `propka` Python package directly from the command line using `propka` instead of the `propka3` executable, which is the actual command-line tool installed with the package.
fixUse the `propka3` executable for command-line invocation (e.g., `propka3 FILENAME.pdb`) or run it as a Python module using `python -m propka FILENAME.pdb`.
WARNING: PropKa failed on this structure - disabling use of PropKa
This error typically occurs when `propka` is used as a component within another software (like Schrödinger's Protein Preparation Wizard) and is often due to file permission problems with the `$HOME/.python-eggs` directory on Linux systems.
fixChange the permissions of the `$HOME/.python-eggs` directory to allow write access for the user (e.g., `chmod -R 777 $HOME/.python-eggs`). If owned by root, you might also need to change ownership using `sudo chown -R yourusername:yourgroup $HOME/.python-eggs`.
AttributeError: 'NoneType' object has no attribute '...' (during PDB processing)
This error indicates that an operation was attempted on an object that is `None`, suggesting an issue where `propka` failed to properly parse or process the input PDB file, possibly due to malformed, incomplete, or unexpected atomic/residue definitions.
fixCarefully check the input PDB file for structural issues like missing atoms (e.g., OXT atoms at C-termini), incorrect formatting, or non-standard residues. Pre-processing the PDB file with dedicated tools like PDB2PQR might help resolve common input problems.
ModuleNotFoundError: No module named 'propka'
This error indicates that the `propka` Python package is either not installed in the current environment or the Python interpreter cannot find it in its search path.
fixInstall or reinstall the `propka` package using pip: `pip install --upgrade propka`. Ensure you are working within the correct Python environment if using virtual environments.
pkg_resources.DistributionNotFound: The 'PROPKA==X.Y.Z' distribution was not found
This error points to an issue where `pkg_resources` (part of `setuptools`) cannot locate the metadata for the installed `propka` distribution, often due to a corrupted installation or an outdated `setuptools` version.
fixTry reinstalling `propka` in a clean virtual environment using `pip install --upgrade propka`. If the problem persists, upgrade `setuptools` (`pip install --upgrade setuptools`) and then reinstall `propka`.
Upgrade
Version history
3.5.1latest on PyPI · released Jan 2, 2024
Audit
Dependencies
PythonrequiredRuntime environment. PROPKA 3 requires Python 3.10 or higher.