PySCF: a Python quantum chemistry framework you drive from scripts

What PySCF solves, and who ends up using it

Electronic structure codes have historically been monolithic executables: you write an input file in a bespoke format, run a binary, and parse a text output. PySCF takes the opposite position. The package describes itself as a Python-based simulations of chemistry framework, and the repository layout backs that up: the top-level pyscf/ directory holds the method implementations, while examples/ is organised by method rather than by workflow, with subdirectories named adc, agf2, cc, ci, df, dft, fci, geomopt, grad, gto, gw, mcscf, md, mp and more. Each of those is a family of methods you import and call.

The audience follows from that shape. If you are a method developer who needs to modify a Hamiltonian, swap an integral engine, or build a new coupled-cluster variant on top of existing tensor contractions, having the whole stack as importable Python is the point. If you are a computational chemist running a fixed set of standard calculations and reporting energies, the same design is a cost: you supply the control flow that a traditional code would supply for you. The pyproject.toml classifiers list the intended audience as Science/Research and Developers, which is an honest description of where the project sits.

How the Python layer sits over the compiled kernels

PySCF is not pure Python. The build system in pyproject.toml requires setuptools, wheel and cmake<4.0, and setup.py imports Extension from setuptools, so a source build compiles native code alongside the Python modules. The runtime dependencies are short and conventional: numpy>=1.13 (excluding 1.16 and 1.17), scipy>=1.6.0, h5py>=2.7, setuptools, and psutil on Windows only. Nothing exotic, which matters if you are installing into a shared cluster environment.

The data flow a user sees is object-oriented rather than file-oriented. A molecule is described by its geometry and basis, integrals are produced by a gto layer, and a method object consumes those integrals. Because the layers are separate Python modules, you can substitute one piece without rewriting the rest. That is also why the README is explicit that density functional calculations depend on external libraries: PySCF does not implement density functionals itself and delegates their evaluation, so the README asks you to cite Libxc or XCFun separately when your calculation used them. That is an architectural fact with a citation consequence, not a footnote.

The extension mechanism is the other structural choice worth noting. Rather than growing the core indefinitely, the project keeps a set of modules as separately installable extensions: the README names dispersion, dmrgscf, fciqmc, icmpspt, properties, semiempirical and shciscf among others. The pyproject.toml optional-dependencies table maps extras such as geomopt, doci, properties, semiempirical, cppe, pyqmc and bse onto concrete packages. You install what you use.

Installing PySCF and running a first calculation

The README gives a single command for the stable release. It pulls the published wheel, so on a platform with a matching wheel you avoid the cmake build entirely.

pip install pyscf

After that, `import pyscf` in a Python session should succeed and `pyscf.__version__` should report the installed version. The README points at the installation manual at pyscf.org for custom builds, including build-from-source instructions.

If you want methods that are still under development, the README directs you to a separate package rather than to a git checkout:

pip install pyscf-forge

Extensions are installed either all at once or individually. The README shows both forms, and the individual form is the one to prefer when you know which module you need:

pip install pyscf[all]
pip install pyscf[dispersion]

For a first real calculation, the repository ships examples/0-readme.py, which is the README example, and examples/h2o.py, which is a water molecule. Those two files are the intended entry point, and the examples/ tree continues with method-specific directories (examples/dft, examples/cc, examples/mcscf and others) that you can run as-is before adapting them to your own system. The pattern to expect is: build a molecule object, attach a basis, construct a method object, call a run method, then read attributes off the resulting object rather than grepping a text file.

What you have to bring yourself

The base install does not include geometry optimisation. The pyproject.toml geomopt extra lists pyberny>=0.6.2, geometric>=0.9.7.2 and pyscf-qsdopt as separate dependencies, and the examples/geomopt directory exists to exercise them. If your workflow is optimise-then-single-point, you are assembling that pipeline from at least two packages.

The same pattern applies elsewhere. The properties extra, the semiempirical extra, the doci extra and the bse extra are all optional; the base package is the electronic structure core. A user coming from a code where solvent models, thermochemistry and dispersion corrections are menu items will find that PySCF asks them to install each of those and to know which one they want.

There is also a citation obligation that is unusual in its specificity. The README states that the base PySCF paper should be cited in publications using the package, and that Libxc or XCFun should additionally be cited when density functional calculations used them. If you are publishing, that means tracking which functional backend your run touched. The README does not document a mechanism for recording that automatically.

Finally, the project's own bug and feature channel is the GitHub issues page, as stated in the README. There is no separate support desk described.

PySCF against ORCA, Psi4 and the plane-wave codes

People search for PySCF versus ORCA, Psi4, Gaussian, VASP and Quantum Espresso, and the comparisons are not all of the same kind. VASP and Quantum Espresso are plane-wave, periodic-solids codes; PySCF's examples tree is built around molecular electronic structure (cc, ci, fci, mp, mcscf, gw), so that comparison is about the physical system, not about which code is better.

The closer comparison is Psi4, which also presents itself as a Python-drivable electronic structure package. The difference visible in this repository is in how extensions are packaged: PySCF keeps a core plus a set of separately installed modules reachable through extras in pyproject.toml and through pyscf-forge, so the dependency footprint of a minimal install is numpy, scipy and h5py. That is a deliberate split, and it means the answer to "does PySCF do X" often depends on whether you installed the extra that provides X.

Against a commercial GUI code such as Gaussian or ORCA, the difference is the interface contract. PySCF hands you Python objects and expects you to script the workflow; the others hand you an input format and a binary. Neither is a defect. It does mean that PySCF's learning curve is a Python learning curve plus a methods learning curve, and the documentation at pyscf.org is the place that curve is meant to be climbed.

Release cadence, licence and the cost of upgrading

The repository is not archived and the last push was on 2026-07-18, the same date as the v2.14.0 release. The two prior releases were v2.13.1 on 2026-06-03 and v2.13.0 on 2026-04-21, so the project has shipped on a roughly two-month cadence through 2026. A CHANGELOG file sits at the top level, and the README links to it, which is where you should look before moving a production script onto a new minor version.

The licence is Apache-2.0, declared in both pyproject.toml and the LICENSE file, with a NOTICE file at the top level. Apache-2.0 is permissive and includes a patent grant, but it also carries notice and attribution conditions, and the citation requirements in the README sit on top of the licence rather than being part of it. This is not legal advice; if you are redistributing PySCF inside a product or a managed environment, read LICENSE and NOTICE yourself and check whether your organisation's policy treats the citation request as a condition.

The upgrade cost is mostly in the optional layer. Because geomopt, properties, semiempirical and the rest are separate distributions with their own version constraints, a core upgrade can leave an extension pinned to an older release. Pin the core version explicitly in your environment file and re-run the examples/ script closest to your method after upgrading, rather than assuming a minor bump is inert.

Editorial conclusion

Adopt PySCF if your work is scripted electronic structure and you are comfortable reading method documentation rather than clicking through a GUI. Do not adopt it if you need a point-and-click workflow, a built-in functional library, or a tool that ships its own geometry optimiser and solvent models in the base install. Before committing, verify three things: that your Python version meets the >=3.7 requirement in pyproject.toml, that the optional extras you need (geomopt, properties, semiempirical) install cleanly on your platform, and that the specific method you plan to run is exercised by a file under examples/ that you can reproduce on your own molecule.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. Release notes