PyMOL commands cheat sheet, runnable in the browser
Fetch, colour, select, measure, align and render one structure, 1HSG, command by command
Matic Broz, PhD15 min

Most PyMOL tutorials start with an installer. The commands themselves are short, though, and you can type them in a browser tab. The PDB viewer has a command line that reads PyMOL syntax, so fetch, select, color, distance, align and png mean what they mean in PyMOL, and this page runs each of them on one structure.
The structure is 1HSG, HIV-1 protease bound to the inhibitor indinavir, which the entry calls L-735,524 and the file labels MK1.[14] It is a small homodimer of two 99-residue chains with one ligand, so every command below does something you can see. The second structure for the alignment is 1HVR, the same enzyme with a different inhibitor.[15]
Work through the sections in order and you end with a figure, a measured contact list, an alignment and a script. Each block can be pasted whole into the command line. Commands that PyMOL has and the viewer does not are collected in one short section instead of mixed into the blocks.
How to type PyMOL commands in the browser
- Open the PDB viewer.
- Click Command line at the bottom of the canvas. A line with a log above it opens.
- Type
fetch 1hsgand press Enter. The structure loads and the log saysFetched 1hsg. - Type the next command. The up and down arrows recall earlier lines, and Tab completes command names, object names, colours and settings.
You can also type a command into the search box at the top. A line whose first word is a command and that has arguments, such as show sticks, organic, runs as a command there, and a leading > forces it. Separate several commands on one line with ;, or paste several lines at once to run them as one script and one undo step.
Selections follow PyMOL's syntax, including object names (1hsg and chain A) and the slash form (/1hsg//A/25/CA).[3] The log keeps recent commands and their output, which is where RMSD values and atom counts appear.
The commands you will use most
| Command | What it does | Example |
|---|---|---|
fetch | Downloads an entry by its PDB code and loads it | fetch 1hsg |
show, hide, as | Turn representations on or off for a selection; as shows one and hides the rest | show sticks, organic |
color | Sets the colour of an object or selection | color gray80, polymer |
util.cbc | Colours each chain differently | util.cbc |
spectrum | Colours by a property such as b along a palette | spectrum b, blue_white_red |
select | Stores a named selection from an atom expression | select site, resn MK1 |
distance | Measures distances; mode=2 keeps polar contacts only | distance hb, site, pocket, mode=2 |
label | Writes an expression per atom as a label | label name CA, resn + resi |
align | Sequence alignment, then a fit with outlier rejection | align mobile, target |
super | Structure-based fit that does not depend on sequence | super mobile, target |
cealign | CE structural alignment; target comes first | cealign target, mobile |
zoom, orient | Frame a selection, or line its principal axes up with the screen | zoom site, 8 |
png, ray | Save the view as an image; trace rays for lighting | png figure.png, 10cm, dpi=300 |
How to load a structure and change how it looks
fetch takes a PDB code, saves the file and loads it as an object named after the code.[1] hide everything clears the default look, and show then switches on exactly what you ask for.
fetch 1hsg
hide everything
show cartoon
util.cbc
show sticks, organic
util.cbag organicorganic is PyMOL's keyword for non-polymer organic molecules, so here it means the inhibitor.[3] util.cbc colours each chain a different colour. util.cbag organic then colours the ligand's non-carbon atoms by element and leaves its carbons green, the PyMOL default.
Open this view in the PDB viewer.
How to colour in PyMOL
color name, selection colours whatever you select. It accepts a colour name, 0xRRGGBB and atomic, and the selection defaults to everything.[14] util.cbc is the one-word way to give every chain its own colour, and spectrum colours along a palette by an atom property. In the viewer the colour names, #RRGGBB, [r, g, b] and set_color all work.
color gray80, polymer
color tv_orange, chain B and polymer
color atomic, organicThe first line turns both chains grey, the second recolours chain B, and the third puts the ligand back to element colours. Colour names such as gray80 and tv_orange are PyMOL's own.
How to select atoms
select name, expression stores a named selection, and later commands can use the name in place of an expression.[2] With one argument it names the selection sele. The expression language combines keywords with and, or and not, and adds spatial operators such as within, which picks atoms inside a distance of another selection, and byres, which grows a selection to whole residues.[3]
select site, resn MK1
select pocket, byres (polymer within 4 of site)
show sticks, pocketsite is the inhibitor and pocket is every protein residue with an atom within 4 Å of it. Ask the viewer how large each one is with count_atoms site and count_atoms pocket. On 1HSG the log answers 45 atoms for site, the whole of indinavir without hydrogens, and 258 atoms for pocket, 36 residues across both chains.
How to measure distances and find polar contacts
distance name, selection1, selection2 draws dashed lines between two selections. Mode 2 keeps only polar contacts, pairs of donor and acceptor atoms close enough to hydrogen bond.[4] In the viewer, mode 2 considers nitrogen and oxygen atoms and a 3.6 Å limit unless you give a cutoff.
distance hb, site, pocket, mode=2
label pocket and name CA, resn + resi
set label_size, 14
zoom site, 8The label line writes residue name and number on the alpha carbon of each pocket residue. resn + resi is an expression evaluated for every selected atom, and the viewer accepts the same properties, strings and arithmetic you would use in PyMOL. zoom site, 8 frames the ligand with an 8 Å border.
The log answers hb: 9 polar contacts within 3.6 Å. The central hydroxyl of indinavir, atom O2, sits between the two catalytic aspartates: distance chk, resn MK1 and name O2, resi 25 and name OD1+OD2 finds four distances from 2.63 to 3.04 Å, one to each carboxylate oxygen of Asp25 in both chains.
Open this view in the PDB viewer.
To read the contacts as a table with distances and angles, PLIP takes the same file and lists every interaction. Protein-ligand interactions explains what each contact type means.
How to align and superimpose two structures
align makes a sequence alignment between two selections, fits the matched atoms, then runs refinement cycles that reject outliers.[6] super fits by structure, so it still works when sequences differ, and cealign runs the CE algorithm with the target first and the mobile structure second.[6] Load 1HVR beside 1HSG and fit one chain onto the other.
fetch 1hvr
align 1hvr and chain A, 1hsg and chain A
super 1hvr and chain A, 1hsg and chain A
cealign 1hsg and chain A, 1hvr and chain APrefix selections with the object name, as above. Once two objects are loaded, chain A alone matches both. The log prints an RMSD for each fit. In the viewer, align follows PyMOL's method on the Cα atoms and prints the RMSD before and after refinement, while super and cealign both run TM-align, so cealign keeps PyMOL's argument order but not the CE algorithm.
On these two entries align prints RMSD = 0.362 Å (93 to 93 atoms), after 2 refinement cycles. Before refinement: 0.420 Å over 99 atoms., and super and cealign both print 0.420 Å over 99 residues with a TM-score of 0.987. The same enzyme with two different inhibitors barely moves: refinement only drops the 6 least well fitting Cα atoms, which takes the RMSD from 0.42 to 0.36 Å.
Open this view in the PDB viewer.
alignto 1hsg fits every other open object onto 1HSG in one command and lists the RMSD and TM-score of each. For the numbers themselves, RMSD explains what a fit does and does not tell you, and superimpose protein structures compares the methods across programs.
The ChimeraX version
ChimeraX's matchmaker also starts from a sequence alignment and then fits one atom per residue, the alpha carbon for protein.[12] The viewer reads ChimeraX's form too.
matchmaker all to 1hsg/Amm is the short form. It fits every other model onto chain A of 1HSG. ChimeraX numbers models as #1, #2, and the viewer accepts those in specifications as well.
How to colour by B-factor
The B-factor column records how much each atom's position smears in the crystal, and spectrum b turns it into a colour gradient. The command takes an expression, a palette and a selection, and b is one of the expressions it understands.[5]
spectrum b, blue_white_red, polymerBlue is the lowest value in the selection and red the highest, and the log gives the range: Colored by B-factor from 8.76 to 76.16. The flaps that close over the inhibitor are not where the reds are in 1HSG. The two surface loops of chain A around residues 16 to 18 and 64 to 69 are, with Cα B-factors near 60 Ų, while the core and the flaps stay blue.
Open this view in the PDB viewer.
The same colouring in ChimeraX reads attributes instead:
color byattribute bfactor /A palette rainbow range 10,60ChimeraX also has color bfactor, and its range option fixes the ends of the scale.[13] The viewer runs the byattribute form shown above.
How to save an image with png and ray
png filename, width, height, dpi writes the current view. Sizes are pixels unless they carry cm, mm or in, and a unit needs a dpi.[7]
ray
png 1hsg.png, 10cm, dpi=300In PyMOL, ray ray-traces the current frame, and png can do it for you with ray=1.[8]
The viewer does it differently. ray switches on ray-traced lighting for the canvas and for every image saved afterwards, and the ray=1 option is accepted but changes nothing, because every image is already rendered off screen. The file name loses any folder, so png ~/Desktop/a.png saves a.png where the browser puts downloads.
How to make a publication-quality protein figure covers backgrounds, lighting and sizes for journals.
How to run a PyMOL script
A PyMOL script is a plain text file of commands, one per line, saved with the extension .pml.[9] PyMOL runs it with @script.pml or File, then Run script. The viewer has no @: drop the .pml file on the canvas, or paste its lines into the command line, and it runs them in order and lists any that failed.
fetch 1hsg
hide everything
show cartoon
color gray80, polymer
select site, resn MK1
select pocket, byres (polymer within 4 of site)
show sticks, site or pocket
distance hb, site, pocket, mode=2
zoom site, 8
png 1hsg_pocket.png, 1600For loops and conditions, a short Python script works in the same place. Paste it into the command line, drop a .py file, or put it between python and python end in a .pml file.
stored.res = []
cmd.iterate("chain A and name CA", "stored.res.append((resi, resn))")
for resi, resn in stored.res:
if resn in ("ASP", "GLU"):
cmd.color("red", f"chain A and resi {resi}")
print(len(stored.res), "residues")This colours every aspartate and glutamate in chain A red and prints how many residues the chain has. With only 1HSG open it prints 99 residues and colours 8 of them, Glu21, Asp25, Asp29, Asp30, Glu34, Glu35, Asp60 and Glu65. If 1HVR from the alignment section is still open, chain A matches both objects and the count is 198. The viewer runs its own Python interpreter inside the page, so it covers loops, functions, f-strings and math, and stops a run after 15 seconds. It has no classes, with blocks or NumPy. PyMOL file types lists what .pml, .py and .pse files hold and how to open each without PyMOL.
Movies, mutations and electrostatics
Three tasks that PyMOL users search for work through different commands in the viewer.
PyMOL builds a movie with mset, mview and mplay. The viewer accepts the same verbs and keyframes whole scenes.
scene 001, store
mset 1 x120
mview store, 1, scene=001
mplay
movie mp4, talk.mp4, 1920, 1080PyMOL's mutagenesis is a wizard in the Wizard menu, with no command form to type.[10] The viewer has its own command instead, mutate A/82 PHE, which swaps valine 82 of chain A for phenylalanine, draws the side chain that clashes least and lists the rotamers in the side panel.
PyMOL's APBS support is a plugin that needs the apbs and pdb2pqr programs installed.[11] The viewer has its own electrostatics coulombic command, which colours the surface by a Coulombic estimate in the browser, and PDB2PQR prepares a structure for APBS if you want to run it yourself.
Commands that do not run in the viewer
The viewer answers not supported yet: <command> for PyMOL commands it has no equivalent for, and for any first word it does not know. wizard and pseudoatom are two. set works only for the settings that help set lists, and run file.pml explains that the file has to be dropped on the canvas instead. A line that is valid Python, such as x = 5, runs as Python rather than being rejected.
Named selections last until you reload the page, and share links do not carry them. A scene made only of files from your own computer cannot be shared by link at all.
Common mistakes
| Problem | Symptom | Fix |
|---|---|---|
cealign arguments in the align order | The reference structure moves instead of the model | Write cealign target, mobile; align and super take mobile first |
chain A with two objects loaded | A colour or fit hits both structures | Start the selection with the object name, as in 1hsg and chain A |
A set name the viewer does not map | The log says not supported yet: set name | Run help set for the settings it accepts |
Expecting ray to save an image | Nothing is downloaded after ray | Follow it with png name.png, 2400 |
| Reloading the page | Named selections such as site are gone | Run the select lines again, or save a session file under Export |
@script.pml in the command line | not supported yet | Drop the file on the canvas or paste its lines |
After the commands
A figure usually leads to the next question: whether the structure deserves trust, or how a docked pose compares with it. Open a PDB file covers getting your own structures into the viewer, PyMOL licence and download options covers installing PyMOL itself, and Ramachandran plot checks the backbone.
FAQ
What are the most useful PyMOL commands?
fetch to load an entry, show and hide for representations, color and spectrum for colour, select for named selections, distance for contacts, align or super to superimpose, and png to save an image. Table 1 lists each with an example.
Can I run PyMOL commands without installing PyMOL?
Yes, for the commands in this guide. The PDB viewer runs them in your browser tab, and anything it does not recognise is reported as not supported yet.
How do I show polar contacts in PyMOL?
Use distance name, selection1, selection2, mode=2. It draws dashes between donor and acceptor atoms of the two selections that are close enough to hydrogen bond.
What is the difference between align, super and cealign?
align starts from a sequence alignment, so it suits close homologs. super and cealign compare structure and work when the sequences differ, and cealign takes the target first.
Are there ChimeraX equivalents?
For several, yes. matchmaker, color byattribute and clip run in the viewer in their ChimeraX forms, as do clashes and contacts.


