Install & Compatibility
Where this runs
tested against v0.3.29 · 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
195MB installed
● package 195MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
*
✓ from fmpy import *
Common for quick scripts to get all top-level FMPy functions
simulate_fmu
✓ from fmpy import simulate_fmu
Direct import for the main simulation function
read_model_description
✓ from fmpy.model_description import read_model_description
For inspecting FMU metadata
plot_result
✓ from fmpy.util import plot_result
Utility for plotting simulation results
This quickstart demonstrates how to load an FMU, retrieve its metadata, simulate it for a specified duration, and then plot selected simulation results using FMPy. It highlights the core `simulate_fmu` and `plot_result` functions. Users need to provide an actual FMU file (e.g., 'Rectifier.fmu') for the code to run successfully.
import os
from fmpy import simulate_fmu, dump
from fmpy.util import plot_result
# NOTE: FMPy requires an FMU file to operate.
# For this example, you would typically download one, e.g., 'Rectifier.fmu'
# from the FMPy GitHub repository or create your own.
# For demonstration, we'll assume 'Rectifier.fmu' is in the current directory.
fmu_path = 'Rectifier.fmu' # Replace with actual path to your FMU file
if not os.path.exists(fmu_path):
print(f"Error: FMU file '{fmu_path}' not found. Please provide a valid FMU file.")
# Example of how you might download one for a real quickstart:
# from fmpy.util import download_file
# download_file('https://github.com/CATIA-Systems/FMPy/raw/main/FMPy/fmus/Rectifier.fmu', fmu_path)
exit()
# Get information about the FMU
print(f"\nFMU Information for {fmu_path}:")
dump(fmu_path)
# Simulate the FMU
print(f"\nSimulating {fmu_path}...")
result = simulate_fmu(fmu_path, stop_time=1.0)
# Plot the results
print("\nPlotting results...")
plot_result(result, variables=['Rectifier1.Capacitor1.v', 'Rectifier1.Diode1.i'])
print("Plot generated (a new window should appear).")
fmpy --version
Debug
Known issues
gotchaFMPy's full functionality often relies on optional dependencies (e.g., for plotting or GUI). Using `pip install fmpy[complete]` is recommended for a full-featured experience, otherwise, you might miss certain tools.fixInstall with `pip install fmpy[complete]` or manually install needed extras like `matplotlib`, `plotly`, `pyqt`.
affects: All versions
breakingFMI 3.0 FMUs might not always implement all API functions declared in `fmi3Functions.h`, leading to errors like 'Function fmi3InstantiateModelExchange is missing in shared library' during initialization. This is due to strict FMI 3.0.1 specification regarding API implementation.fixEnsure the FMU vendor provides a compliant FMU that implements all specified FMI API functions, even if unused, or report the issue to the FMU vendor. Consider downgrading the FMI version of the FMU if possible.
affects: FMPy versions interacting with FMI 3.0 FMUs.
gotchaThe plotting backend for the FMPy GUI is transitioning. Older versions primarily used `pyqtgraph` and `matplotlib`, but recent updates are moving towards `plotly`. This might lead to unexpected plot rendering issues or require different dependencies.fixIf experiencing plotting issues, ensure `plotly` is installed (`pip install plotly`) and check FMPy's latest documentation or release notes for the recommended plotting backend. If using the GUI, ensure `pyqt` is also installed (`pip install pyqt`).
affects: 0.3.x (especially newer minor releases)
gotchaOn Windows, the `pywin32` package is an optional dependency for some functionalities. Without it, certain platform-specific features or behaviors might not work as expected.fixEnsure `pywin32` is installed on Windows systems using `pip install pywin32` or by installing `fmpy[complete]`.
affects: All versions on Windows
Errors
Common errors & fixes
Function fmi3InstantiateModelExchange is missing in shared library
An FMI 3.0 FMU does not implement all API functions required by the FMI 3.0.1 specification, even those for interface types or optional capabilities the FMU doesn't support.
fixContact the FMU vendor to request a compliant FMU that includes all necessary FMI API function implementations. Alternatively, try to use an FMI 2.0 version of the FMU if available.
Unable to change tunable parameters using either apply_starting_values, setReal() or start_values.
This error occurs when attempting to modify FMU parameters, which may not be accessible for scripting or might be incorrectly set as non-tunable.
fixEnsure the parameters you are trying to change are correctly defined as tunable in the FMU's `modelDescription.xml`. Use the `dump()` function to inspect the FMU's variables and their causality/variability. If the parameter is not tunable, it cannot be changed at runtime. Consult the FMU's documentation or creator. For initial values, ensure you are passing a `start_values` dictionary correctly to `simulate_fmu`.
Plot in generated jupyter notebook not visible
Generated Jupyter notebooks may sometimes fail to display plots, potentially due to missing or conflicting plotting dependencies or environment issues within Jupyter.
fixEnsure `plotly` and `jupyter-nbformat` (if generating notebooks) are correctly installed (`pip install plotly jupyter-nbformat`). Restart the Jupyter kernel. Verify that the output of `plot_result` is displayed if run directly in a Python script, as a troubleshooting step.
Upgrade
Version history
0.3.29latest on PyPI · released Mar 24, 2026
Audit
Dependencies
lxmlrequiredRequired for parsing modelDescription.xml
numpyrequiredRequired for simulating FMUs
pywin32optionalOptional, required for full functionality on Windows systems
matplotliboptionalOptional, for plotting results (part of `[plot]` extra)
plotlyoptionalOptional, increasingly used for GUI plots, replacing `pyqtgraph` and `matplotlib` in some contexts
scipyoptionalOptional, part of the `[plot]` extra
daskoptionalOptional, for parallelization examples
requestsoptionalOptional, for downloading example FMUs
pyqtoptionalOptional, required for the graphical user interface