Common PyMOL Mistakes and How to Fix Them: Troubleshooting Guide
Most PyMOL problems have simple causes and two-line fixes — but only if you know where to look. These are the ten issues that appear most often in PyMOL help threads, lab Slack channels, and frustrated emails to supervisors at 11pm before a paper deadline.
You load an MD trajectory and the protein looks shattered — chains and atoms scattered across the box, disconnected, nowhere near each other. This is not a PyMOL bug. It’s periodic boundary condition (PBC) artifacts in the raw trajectory: atoms that crossed the simulation box boundary during MD appear on opposite sides of the box in the coordinates.
gmx trjconv -s md.tpr -f md.xtc -o md_whole.xtc -pbc wholegmx trjconv -s md.tpr -f md_whole.xtc -o md_vis.xtc -center -pbc mol -ur compactFor AMBER, run
autoimage then center in cpptraj. Then load the processed trajectory into PyMOL.
You set bg_color white, ray trace, export a PNG — and the background renders as black, gray, or the checkered transparency pattern when dropped into PowerPoint or Word. The cause is almost always ray_opaque_background being set to 0 (off), which makes PyMOL render a transparent background regardless of what color you set.
bg_color white:bg_color whiteset ray_opaque_background, 1Put both lines in every figure script. The
bg_color sets what you see interactively; ray_opaque_background controls what gets rendered into the exported file. You need both.
Ray tracing a complex scene with surfaces, many objects, and large proteins can take 20–40 minutes or crash with an out-of-memory error. Three culprits cause almost all ray trace slowdowns: high surface quality settings, a very large pixel count, and too many loaded objects in the session.
delete unused_object. Lower surface quality while working interactively and raise it only for the final export: set surface_quality, 0 (interactive) vs set surface_quality, 2 (export). Render at the minimum pixel count that meets your journal’s DPI requirement — a single-column figure rarely needs more than ray 1200, 900. If PyMOL still crashes, try the open-source version compiled without memory limits, or render headless with pymol -c script.pml where there is no GUI overhead.
You color the protein blue, then show the surface — and the surface is gray. Or you color the surface red, and it shows as the atom color instead. Surfaces in PyMOL can be colored independently of the underlying cartoon/sticks representation, and they have their own color state that can override atom-based coloring.
show surface may not propagate to the surface. Apply colors after adding the surface representation, or explicitly target the surface:show surfacecolor slate, chain A ← apply after show surfaceTo force a specific surface color regardless of atom colors:
set surface_color, white ← overrides everything with whiteTo reset surface color back to following atom colors:
set surface_color, default
You run select site, resi 100 and chain A and get zero atoms selected, or the selection highlights something completely wrong. Three causes account for most broken selections: wrong residue numbering (the PDB uses author numbering which may differ from sequence numbering), wrong chain ID case (chain A ≠ chain a), or the residue being a HETATM not covered by standard selection keywords.
iterate all, print(chain, resi, resn) (or just the first 50: iterate first 50, print(chain, resi, resn)) to see the actual chain IDs and residue numbers as PyMOL sees them. Chain IDs are case-sensitive. For heteroatoms like ligands, use hetatm or resn LIG rather than resi. If residue numbers look right but atoms aren’t selected, check for insertion codes: residue “100A” uses resi 100A syntax.
You run spectrum b, blue_red on an AlphaFold structure and the whole protein appears nearly the same color — no visible gradient. The cause is almost always the missing minimum and maximum arguments. Without them, PyMOL scales the gradient to the actual min and max B-factor values in the file, which compresses the useful confidence range into an invisible gradient.
spectrum b, blue_cyan_yellow_orange_red, minimum=50, maximum=100The
minimum=50 clamps the lower end so everything below 50 gets the same “lowest” color, and the gradient covers the meaningful 50–100 range. Without these arguments, a protein where pLDDT ranges from 48 to 97 shows an almost invisible gradient because PyMOL spreads the full color scale across only a 49-unit range. Always specify both arguments for AlphaFold structures.
The most common session save failure: the .pse file saves without error, but when you load it the next day the structure looks different — wrong orientation, missing colors, different representations. This almost always happens because PyMOL saves the state of all objects in the session, but if you’ve loaded large external files (trajectories, maps) they may not embed correctly in all versions.
log_close or manually:save session.pse ← for quick restorationsave session.pml ← text record of all commands for robustnessAlso, if you are using trajectories, the trajectory file is referenced by path — not embedded. If you move the XTC file, the PSE can’t reload it. Keep PSE and trajectory files in the same directory and use relative paths.
You run distance hbonds, LIG, pocket, mode=2 and nothing appears — or only one or two bonds show when you know there are more. PyMOL’s H-bond detection uses a geometric criterion based on donor-acceptor distance and angle, but it also requires hydrogen atoms to be present in certain configurations. Many PDB files don’t include hydrogens, causing H-bond detection to miss bonds.
distance contacts, LIG, pocket, 3.5If contacts appear but
mode=2 doesn’t, the issue is likely missing hydrogens. Add them: h_add (adds hydrogens computationally). Then retry distance hbonds, LIG, pocket, mode=2. For more accurate H-bond detection, use PLIP (plip-tool.org) which handles missing hydrogens properly.
Your figures show flat ribbon helices instead of the smooth, rounded tube-style helices seen in most publications. This is a setting that’s off by default — PyMOL uses a simpler flat helix representation unless you enable fancy helices explicitly.
set cartoon_fancy_helices, 1Add this to every figure script. While you’re at it, enable smooth loops too:
set cartoon_smooth_loops, 1If you want these settings every time PyMOL opens, add both lines to your PyMOL config file (
~/.pymolrc on Mac/Linux or pymolrc.pml in the PyMOL installation directory on Windows). Anything in that file runs automatically at startup.
The GUI opens but the 3D viewer is black or blank — or structures load but don’t render visually. The cause is almost always an OpenGL or graphics driver problem: PyMOL’s 3D viewer requires hardware-accelerated OpenGL and can fail when drivers are outdated, when running over a remote connection, or when there’s a conflict with virtual display environments.
pymol -M to disable hardware acceleration (software rendering — slower but works anywhere).Remote/SSH: PyMOL’s viewer can’t render over SSH without X11 forwarding. Either forward X11 (
ssh -X) or run PyMOL headless (pymol -c script.pml) to generate figures without a display.On macOS Apple Silicon: Use the conda-forge build —
conda install -c conda-forge pymol-open-source. The arm64 native build resolves most display issues on M-series Macs.On Windows: Update your graphics drivers from the GPU manufacturer (NVIDIA, AMD, or Intel), not from Windows Update.
Quick troubleshooting reference
| Symptom | Most likely cause | Fix |
|---|---|---|
| Fragmented / exploding structure | Raw MD trajectory with PBC artifacts | gmx trjconv -pbc whole then -center |
| Gray or black PNG export | ray_opaque_background = 0 | set ray_opaque_background, 1 |
| Very slow ray trace | High surface quality or too many objects | Reduce surface_quality, delete unused objects |
| Surface wrong color | Color applied before show surface | Color after show surface, or set surface_color |
| Selection zero atoms | Wrong chain ID, residue number, or HETATM | iterate all, print(chain, resi, resn) to inspect |
| pLDDT coloring flat | Missing minimum/maximum arguments | spectrum b, …, minimum=50, maximum=100 |
| Session loads differently | PSE version mismatch or missing trajectory | Save PML script alongside PSE |
| H-bonds not showing | Missing hydrogens in PDB file | h_add then retry distance mode=2 |
| Flat ribbon helices | cartoon_fancy_helices = 0 | set cartoon_fancy_helices, 1 |
| Black viewer window | OpenGL / driver issue | pymol -M or update GPU drivers |
~/.pymolrc on Mac/Linux) so they’re always active. A good starting .pymolrc:set cartoon_fancy_helices, 1set cartoon_smooth_loops, 1set ray_opaque_background, 1bg_color whiteThese four lines eliminate problems 2 and 9 permanently — you never need to remember to set them again.
reinitialize to reset everything to factory defaults, then reload your structure from scratch. Most persistent weirdness disappears after a clean reinitialize — it’s the equivalent of turning it off and on again, but without losing the loaded files.
The pattern behind most PyMOL problems
Nine of these ten problems are either missing a single command (ray_opaque_background, cartoon_fancy_helices, minimum=50), applying commands in the wrong order (coloring before showing surface), or not preprocessing input data (raw MD trajectories). None of them are bugs — they’re all predictable consequences of defaults that weren’t designed for publication figure workflows. Put the four-line .pymolrc setup in place, always preprocess trajectories before loading, and color after showing representations, and you’ll avoid the majority of issues on this list before they happen.