Launching From a Script
The recommended way to run PyMOL-Python scripts is by using PyMOL as the interpreter. This is supported by all versions of PyMOL, including the pre-compiled bundles provided by Schrödinger.
Example from a shell:
shell> pymol -cq script.py
With arguments (sys.argv becomes ["script.py", "foo", "bar"]):
shell> pymol -cq script.py -- foo bar
Example from a running PyMOL instance:
PyMOL> run script.py
For advanced users, the following PyMOL versions also allow to run PyMOL from an existing Python process:
- PyMOL 2.0 based on Anaconda (using Anaconda's python, which is included in bundles provided by Schrödinger)
- Open-Source PyMOL
- Schrödinger-provided "Mac alternative X11-only build" of the 1.8.x series
After importing the pymol module, PyMOL's event loop has to be started with a call to pymol.finish_launching() (not supported on macOS).
With PyMOL 2.1, calling any pymol.cmd function will automatically start a backend process without the GUI in the main thread. "finish_launching" should not be necessary, and will launch PyMOL in a new thread with an event loop, which will cause 100% CPU usage (at least with "-c").
from pymol import cmd cmd.fragment('ala') cmd.zoom() cmd.png('/tmp/test.png', 300, 200)
Since PyMOL 1.7.4, the following form is sufficient:
This is not supported on macOS (see bug report)
import pymol pymol.finish_launching(['pymol', '-q'])
Before 1.7.4, either "-K" was needed as an additional argument, or arguments had to be assigned to __main__.pymol_argv or pymol.pymol_argv.
Here is an example script that launches PyMol for stereo viewing on a VisBox. It runs PyMol fullscreen stereo, and disables the internal gui. The environment (PYTHON_PATH and PYMOL_PATH) must already be set up for this example to work (see Example 2 below for how to setup within the script).
#!/usr/bin/env python # Tell PyMOL to launch quiet (-q), fullscreen (-e) and without internal GUI (-i) import __main__ __main__.pymol_argv = [ 'pymol', '-qei' ] import pymol # Call the function below before using any PyMOL modules. pymol.finish_launching() # not supported on macOS from pymol import cmd cmd.stereo('walleye') cmd.set('stereo_shift', 0.23) cmd.set('stereo_angle', 1.0)
This script launches PyMOL without any GUI for scripting only. It enables tab-completion on the python command line and does the PyMOL environment setup (you need to adjust the moddir variable!). Hint: You may save this as "pymol-cli" executable.
#!/usr/bin/python2.6 -i import sys, os # autocompletion import readline import rlcompleter readline.parse_and_bind('tab: complete') # pymol environment moddir='/opt/pymol-svn/modules' sys.path.insert(0, moddir) os.environ['PYMOL_PATH'] = os.path.join(moddir, 'pymol/pymol_path') # pymol launching: quiet (-q), without GUI (-c) and with arguments from command line import pymol pymol.pymol_argv = ['pymol','-qc'] + sys.argv[1:] pymol.finish_launching() cmd = pymol.cmd
PyMOL captures sys.stdout and sys.stderr, to control it with it's own feedback mechanism. To prevent that, save and restore both streams, e.g.:
import sys stdout = sys.stdout stderr = sys.stderr pymol.finish_launching(['pymol', '-xiq']) # not supported on macOS sys.stdout = stdout sys.stderr = stderr
Independent PyMOL Instances
It's possible to have multiple independent instances.
import pymol2 p1 = pymol2.PyMOL() p1.start() p2 = pymol2.PyMOL() p2.start() p1.cmd.fragment('ala') p1.cmd.zoom() p1.cmd.png('/tmp/ala.png', 1000, 800, dpi=150, ray=1) p2.cmd.fragment('ser') p2.cmd.zoom() p2.cmd.png('/tmp/ser.png', 1000, 800, dpi=150, ray=1) p1.stop() p2.stop()
Independent PyMOL Instances (Context Manager)
PyMOL 2.2 adds context manager support.
import pymol2 with pymol2.PyMOL() as p1: p1.cmd.fragment('ala') p1.cmd.zoom() p1.cmd.png('/tmp/ala.png', 1000, 800, dpi=150, ray=1)