Cannot import `Interchange` if `openmm` is not installed

[stgeo]

Description

I have a package that depends on openff-interchange but does not install it via conda, so I have to explicitly specify the dependencies from the git repositories:

[project.optional-dependencies]
openff = [
    "openff-toolkit @ git+https://github.com/openforcefield/openff-toolkit@stable",
    "openff-interchange @ git+https://github.com/openforcefield/openff-interchange@v0.3.29",
    "openff-models @ git+https://github.com/openforcefield/openff-models@0.1.2",
    "openff-recharge @ git+https://github.com/openforcefield/openff-recharge@0.5.2",
    "openff-units @ git+https://github.com/openforcefield/openff-units@0.2.2",
    "openff-utilities @ git+https://github.com/openforcefield/openff-utilities@v0.1.12",
    "openforcefields @ git+https://github.com/openforcefield/openforcefields@2024.09.0",
    "networkx",
    "pint",
    "importlib-resources",
    "importlib-metadata",
    "cachetools",
    "xmltodict",
    "python-constraint",
]

which works fine. However, bumping the versions to:

[project.optional-dependencies]
openff = [
    "openff-toolkit @ git+https://github.com/openforcefield/openff-toolkit@stable",
    "openff-interchange @ git+https://github.com/openforcefield/openff-interchange@v0.5.4",
    "openff-models @ git+https://github.com/openforcefield/openff-models@0.1.2",
    "openff-recharge @ git+https://github.com/openforcefield/openff-recharge@0.5.3",
    "openff-units @ git+https://github.com/openforcefield/openff-units@0.4.0",
    "openff-utilities @ git+https://github.com/openforcefield/openff-utilities@v0.1.17",
    "openforcefields @ git+https://github.com/openforcefield/openforcefields@2025.10.0",
    ...
]

Importing Interchange as

from openff.interchange.components.interchange import Interchange

I now get an exception:

NameError: name 'openmm' is not defined
Traceback (most recent call last):
  ...
  File "/redacted/.venv/lib/python3.13/site-packages/openff/interchange/components/interchange.py", line 28, in <module>
    from openff.interchange.components.mdconfig import MDConfig
  File "/redacted/.venv/lib/python3.13/site-packages/openff/interchange/components/mdconfig.py", line 12, in <module>
    from openff.interchange.components.toolkit import _get_num_h_bonds
  File "/redacted/.venv/lib/python3.13/site-packages/openff/interchange/components/toolkit.py", line 125, in <module>
    system: openmm.System | None = None,
            ^^^^^^
NameError: name 'openmm' is not defined. Did you mean: 'open'?

The offending code is:

def _simple_topology_from_openmm(
    openmm_topology: "openmm.app.Topology",
    system: openmm.System | None = None,
) -> Topology:

openmm.app is conditionally imported, if installed, and openmm is not imported at all.

Enclosing openmm.System | None in quotes resolves the issue, although it should probably also be imported under if TYPE_CHECKING.

Reproduction

mkdir test && cd test
uv init --python 3.13
uv add "openff-toolkit @ git+https://github.com/openforcefield/openff-toolkit@stable" \
	"openff-interchange @ git+https://github.com/openforcefield/openff-interchange@v0.5.4" \
	"openff-models @ git+https://github.com/openforcefield/openff-models@0.1.2" \
	"openff-recharge @ git+https://github.com/openforcefield/openff-recharge@0.5.3" \
	"openff-units @ git+https://github.com/openforcefield/openff-units@0.4.0" \
	"openff-utilities @ git+https://github.com/openforcefield/openff-utilities@v0.1.17" \
	"openforcefields @ git+https://github.com/openforcefield/openforcefields@2025.10.0" \
	"networkx" \
	"pint" \
	"importlib-resources" \
	"importlib-metadata" \
	"cachetools" \
	"xmltodict" \
	"python-constraint" \
	"packaging"
uv run python -c "from openff.interchange.components.interchange import Interchange"

Output

WARNING: No basic cheminformatics toolkits are available.
At least one basic toolkit is required to handle SMARTS matching and file I/O. 
Please install at least one of the following basic toolkits:
The RDKit : A conda-installable version of the free and open source RDKit cheminformatics toolkit can be found at: https://anaconda.org/conda-forge/rdkit
AmberTools : The AmberTools toolkit (free and open source) can be found at https://anaconda.org/conda-forge/ambertools
Built-in Toolkit : This toolkit is installed with the Open Force Field Toolkit and does not require additional dependencies.
OpenEye Toolkit : The OpenEye Toolkits can be installed via `mamba install openeye-toolkits -c openeye`
OpenFF NAGL : See https://docs.openforcefield.org/projects/nagl/en/latest/installation.html

Traceback (most recent call last):
  File "<string>", line 1, in <module>
    from openff.interchange.components.interchange import Interchange
  File "/redacted/test/.venv/lib/python3.13/site-packages/openff/interchange/components/interchange.py", line 28, in <module>
    from openff.interchange.components.mdconfig import MDConfig
  File "/redacted/test/.venv/lib/python3.13/site-packages/openff/interchange/components/mdconfig.py", line 12, in <module>
    from openff.interchange.components.toolkit import _get_num_h_bonds
  File "/redacted/test/.venv/lib/python3.13/site-packages/openff/interchange/components/toolkit.py", line 125, in <module>
    system: openmm.System | None = None,
            ^^^^^^
NameError: name 'openmm' is not defined. Did you mean: 'open'?

Software versions

• Ubuntu 24.04, see above for the rest.

[mattwthompson]

Thanks for the report, you've stumbled across a few things:

• Conda is the only supported installation pathway right now. There is some motion behind the scenes that @j-wags will hopefully be able to share some public updates on soon, but I don't think that's the case today. (If this is important to your company, support could accelerate this and we'd love to chat!) Until then, pip/uv etc. installs will be a little janky, unstable, and require more than a little effort on users' part.
• The conda package does make an effort to treat OpenMM as an optional dependency, but maybe this is of no consequence because of what other dependencies pull down. I'm not sure
• OpenMM is not treated as optional; in our products it's installed basically everywhere by default, largely because the end state of force field use is typically MD simulations and OpenMM is preferred by our user base. It would be nice to soften this (Ensure basic functionality is accessible without OpenMM installed #1505); however simple the code change is, testing it in perpetuity is not so trivial.
  • As an aside, your traceback indicates you don't have any cheminformatics toolkits installed. Without any of these, I don't think OpenFF infrastructure can load molecule files, prepare topologies, apply partial charges, generally use force fields, or do any of the key use cases I'm aware of. If you're intentionally leaving out these dependencies and able to share anything, I'm curious what you're aiming to do here!

[stgeo]

Thanks for the response @mattwthompson

• Conda is the only supported installation pathway right now. There is some motion behind the scenes that @j-wags will hopefully be able to share some public updates on soon, but I don't think that's the case today. (If this is important to your company, support could accelerate this and we'd love to chat!) Until then, pip/uv etc. installs will be a little janky, unstable, and require more than a little effort on users' part.

I am aware of this limitation and we have been working around it so far. I've also seen some announcements about potentially supporting pip installations in the future, but I understand that this is not a high priority. Currently, our company doesn't rely on OpenFF sufficiently to be able to afford to support the project directly - maybe further down the line.

• The conda package does make an effort to treat OpenMM as an optional dependency, but maybe this is of no consequence because of what other dependencies pull down. I'm not sure

This, along with the try-except imports in the code and some related commit messages, led me to believe that OpenMM is meant to be optional. I understand it is a challenge to test all possible combinations of "sort of optional" features. If the error was in any way related to functionality, I would have assumed that OpenMM simply is mandatory now. But since it's essentially a simple syntax error in a type hint, I thought it's worth reporting and fixing.

This is indeed the same error as #1505, as far as I can see.

• As an aside, your traceback indicates you don't have any cheminformatics toolkits installed. Without any of these, I don't think OpenFF infrastructure can load molecule files, prepare topologies, apply partial charges, generally use force fields, or do any of the key use cases I'm aware of. If you're intentionally leaving out these dependencies and able to share anything, I'm curious what you're aiming to do here!

That was just for the MWE - we do have the RDKit and AmberTools toolkits in the production environment. The latter presents its own set of challenges, because we also don't install AmberTools via conda - but that's a separate topic, pretty much solved on our side.
We basically just use OpenFF to set up a force field for a molecule and then use ORCA as the engine, because it is already integrated with our workflow driver. It's a fairly niche feature for us and not used very much. Hence the low priority, but also my reluctance to add another dependency that we won't actually use.