PyMOL Scripting for Beginners: Automate Repetitive Tasks with Python

Why scripting transforms your PyMOL workflow

Consider what happens when a reviewer asks you to change the color of one figure panel, regenerate it at higher resolution, and add a distance measurement you didn’t show originally. Without a script, this means reconstructing the scene from memory — reloading the structure, reapplying all the coloring and settings, finding the orientation again, and exporting. With a script, it’s editing three lines and running it again.

Scripting also enables tasks that are simply impossible by hand: generating a consistent figure for every structure in a dataset of 50 proteins, labeling every residue in a selection automatically, or printing a table of pLDDT values for all binding site residues across multiple AlphaFold models. The jump from interactive to scripted PyMOL is one of the highest-leverage skill upgrades available to a structural biologist.

Two scripting approaches: .pml and Python

Your first .pml script

Open any text editor — VS Code, Notepad, TextEdit — and save the following as figure1.pml. Every line is a PyMOL command you could type interactively, but saved so you can run the whole sequence in one step.

Run it two ways:

# Type in the PyMOL command line
@/path/to/figure1.pml

# -c flag = command-line mode (no viewer window)
pymol -c figure1.pml

# Output PNG is saved to your working directory

The -c flag is the key to automation — it runs PyMOL without opening any windows, executes the script, saves the output file, and exits. This means you can run PyMOL figure generation as part of any shell script or pipeline without any manual interaction.

Running Python commands in PyMOL

Any Python code can be run directly in the PyMOL command line or embedded in a .pml file. PyMOL commands are available as functions through the cmd module:

# Python runs directly in the PyMOL command line
print("Hello from Python inside PyMOL")

# PyMOL commands are callable as Python functions via cmd
cmd.fetch("4XYZ")
cmd.color("slate", "chain A")
cmd.show("surface", "chain A")

# Use Python variables in PyMOL commands
structure = "4XYZ"
chain = "A"
cmd.fetch(structure)
cmd.color("blue", f"chain {chain}")

# Python control flow inside PyMOL
for color, chain in [("slate", "A"), ("salmon", "B"), ("palegreen", "C")]:
    cmd.color(color, f"chain {chain}")

Iterating over residues and structures

One of the most useful scripting patterns is extracting per-residue data from PyMOL — pLDDT values, RMSD per residue, or atom positions. PyMOL’s iterate command walks every atom matching a selection and runs Python code for each one.

# Print residue number and pLDDT (B-factor) for each Cα
iterate name CA, print(resi, resn, b)

# Collect pLDDT values into a Python list
stored.plddt = []
iterate (chain A and name CA), stored.plddt.append((resi, b))
print(stored.plddt[:5])   # first 5 entries

# Calculate mean pLDDT of a selection
stored.vals = []
iterate (resi 100-200 and name CA), stored.vals.append(b)
mean_plddt = sum(stored.vals) / len(stored.vals)
print(f"Mean pLDDT: {mean_plddt:.1f}")

Batch figure generation

The most powerful application of PyMOL scripting is generating consistent figures for a set of structures automatically. This script fetches a list of PDB IDs, applies identical coloring and settings, and saves one PNG per structure:

# batch_figures.py
from pymol import cmd
import os

# List of PDB IDs to process
structures = ["4XYZ", "5ABC", "6DEF", "7GHI"]
output_dir = "./figures"
os.makedirs(output_dir, exist_ok=True)

# Figure settings — apply once, reuse for every structure
def setup_figure():
    cmd.bg_color("white")
    cmd.set("ray_opaque_background", 1)
    cmd.set("cartoon_fancy_helices", 1)
    cmd.set("ambient", 0.40)
    cmd.set("specular", 0.25)
    cmd.set("light_count", 4)
    cmd.set("antialias", 2)

for pdb_id in structures:
    # Load structure
    cmd.reinitialize()           # fresh state for each structure
    cmd.fetch(pdb_id)
    cmd.as_cartoon()
    cmd.hide("everything", "resn HOH")

    # Color by chain
    cmd.util.cbc()

    # Apply figure settings
    setup_figure()
    cmd.orient()

    # Export
    output_path = f"{output_dir}/{pdb_id}.png"
    cmd.png(output_path, width=1200, height=900, dpi=300, ray=1)
    print(f"Saved: {output_path}")

Run this script and it generates one 300 DPI publication-quality PNG for each structure, all with identical settings, in seconds. The same pattern works for any dataset — AlphaFold models, docking results, MD snapshots — just swap the structure list and loading method.

The cmd API — essential functions

Saving and reusing scripts

Two habits make PyMOL scripts maximally reusable. First, use get_view to capture the current camera orientation and paste the output into your script as a set_view call — this locks the exact angle so the figure looks identical every time it’s generated:

# After positioning the structure exactly as you want it:
get_view

# Copy the printed matrix and add to your script:
set_view (\
     0.756, -0.604,  0.249,\
    -0.023,  0.369,  0.929,\
    -0.654, -0.706,  0.271,\
     0.000,  0.000, -85.00,\
    12.543,  8.210, 10.123,\
    65.000, 105.00, -20.00)

Second, use log_open to record an interactive session as a .pml script automatically:

# Start recording all commands to a file
log_open my_figure.pml

# ... do your work interactively ...
# load, color, orient, measure — all commands are recorded

# Stop recording
log_close

# The file my_figure.pml now contains your entire session
# Clean it up in a text editor, then it's a reusable script