Install & Compatibility
Where this runs
tested against v2025.3.3 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.110s · 90.8MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 4.0s · import 0.106s · 87MB
91MB installed
● package 91MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
monty
✓ import monty as mty
✗ from monty.io import zopen # While technically correct, 'import monty as mty' is the recommended usage pattern to access its modules and avoid potential name clashes.
The official documentation suggests importing the root `monty` module and using it as an alias (e.g., `mty`) to access its various sub-modules and functions, mirroring the standard Python library's structure.
zopen
✓ from monty.io import zopen
✗ from monty import zopen
Many of Monty's utilities are organized into submodules (e.g., `io`, `dev`). Direct import from the root `monty` package for specific functions like `zopen` is incorrect; you must specify the submodule.
This quickstart demonstrates `monty.io.zopen`, a utility that transparently handles compressed (gzip, bzip2) or uncompressed files based on their filename extension. It functions similarly to Python's built-in `open`, abstracting away the compression details.
import monty.io
# Example: Transparently open compressed or uncompressed files
# Create a dummy gzipped file
with open('example.txt', 'w') as f:
f.write('Hello, Monty!\n')
import gzip
with open('example.txt', 'rb') as f_in:
with gzip.open('example.gz', 'wb') as f_out:
f_out.writelines(f_in)
# Use monty.io.zopen to read from the gzipped file
with monty.io.zopen('example.gz', 'rt') as f:
content = f.read()
print(f'Content from gzipped file: {content.strip()}')
# Use monty.io.zopen to write to a bzipped file
with monty.io.zopen('output.bz2', 'wt') as f:
f.write('This is written to a bzip2 file using monty.io.zopen.')
# Verify by reading back
with monty.io.zopen('output.bz2', 'rt') as f:
read_content = f.read()
print(f'Content from bzipped file: {read_content.strip()}')
import os
os.remove('example.txt')
os.remove('example.gz')
os.remove('output.bz2')
Debug
Known issues
gotchaMonty aims to complement the standard library, but be mindful of potential name collisions if you import specific functions that share names with standard library functions (e.g., `open`). Always prefer qualified imports (`monty.io.zopen`) or aliased imports (`import monty as mty`) to avoid unexpected behavior.fixUse `import monty as mty` and access functions via `mty.module.function()` or `from monty.module import function` for clarity and to prevent shadowing standard library names.
affects: All versions
deprecatedThe `monty.dev` module contains a `deprecated` decorator. While this is a utility provided by Monty, using it on your own code implies maintaining deprecation warnings. Ensure you understand its usage, especially when migrating or updating your code to remove deprecated features.fixRegularly review your codebase for deprecated functions or classes marked by `monty.dev.deprecated`. Update your code to use the recommended replacements to avoid future compatibility issues and maintain clean warning logs.
affects: All versions
gotchaThere are several Python libraries published under or related to the name 'monty' (e.g., 'pydantic-monty', 'boppreh/monty', 'libmonty'). Ensure you are installing and using the correct 'monty' library (from `materialsvirtuallab/monty`) for the intended functionalities described as 'missing complement to Python'.fixAlways verify the PyPI package name (`monty`) and the project's official source or documentation (e.g., `materialsvirtuallab/monty` on GitHub) to confirm you are using the intended library. Check import paths as different 'monty' libraries will have different top-level packages.
affects: All versions
breakingOlder documentation mentions Monty supporting Python 2.7-3.x. However, PyPI metadata for the current version (2026.2.18) clearly states `requires_python: >=3.11`. Attempting to use recent versions of Monty with older Python 3 releases (e.g., 3.9, 3.10) will likely result in installation failures or runtime errors.fixEnsure your Python environment is version 3.11 or newer to be compatible with the latest `monty` releases. Check the `requires_python` field on PyPI for specific version constraints.
affects: >=2026.2.18
breakingIn `monty` version 1.0.0, `ruamel.yaml` became the default YAML parser and dumper. If your project previously relied on specific behaviors or features of `PyYAML` (which might have been the default prior to this change) when handling YAML files through Monty, this change could introduce subtle breaking changes in how YAML data is serialized or deserialized.fixIf upgrading from very old versions of `monty` (pre-1.0.0) that used a different YAML backend, review YAML serialization/deserialization logic. Test your application's YAML handling thoroughly to ensure compatibility with `ruamel.yaml`'s behavior.
affects: 1.0.0 and later (prior to 2026.2.18)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'monty'
The 'monty' library is not installed in the active Python environment or is not accessible via the Python path.
fixInstall the library using `pip install monty` or `conda install -c conda-forge monty` if using Anaconda/Miniconda.
MontySyntaxError: ...
The Python code provided to the `Monty` interpreter for sandboxed execution contains syntax errors.
fixReview and correct the syntax of the Python code being passed to the `Monty` object.
MontyRuntimeError: ...
The Python code executed within the `Monty` interpreter encounters a runtime exception (e.g., ZeroDivisionError, IndexError, KeyError).
fixDebug the logic of the Python code running in the `Monty` interpreter to handle or prevent runtime exceptions.
TypeError: object is not callable
When using `MontyRepl`, certain complex comprehension or generator expression patterns can corrupt the interpreter's internal state, causing subsequent function calls to fail.
fixSimplify or refactor the comprehension/generator expressions causing the issue, ensure `MontyRepl` is used with supported patterns, or re-initialize `MontyRepl` if state corruption is suspected.
Upgrade
Version history
2026.7.16latest on PyPI · released Jul 16, 2026
Audit
Dependencies
No dependency data recorded yet.