# FloPy: scripting groundwater models instead of clicking them

> FloPy is the Python package behind the MODFLOW groundwater modelling ecosystem, letting you build a model, run it and post-process the results in one script rather than through a GUI, with support for MODFLOW 6, MODFLOW-2005, NWT, USG, MODPATH, MT3DMS and SEAWAT. It is a USGS project with a permissive licence and a very wide optional dependency list.

**modflowpy/flopy** — A Python package to create, run, and post-process MODFLOW-based models.

- Repository: https://github.com/modflowpy/flopy
- Website: https://flopy.readthedocs.io
- Stars: 640 · Forks: 363
- Language: Python
- License: NOASSERTION
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/modflowpy-flopy

## One script replaces the model editor

FloPy is a Python package to create, run and post-process MODFLOW-based models, and its purpose is to make the whole modelling workflow reproducible in code.

The alternative it replaces is a desktop application. A groundwater model is normally built by drawing a grid, entering cell conductivities, defining boundary conditions, running the solver and then post-processing the heads. Doing that by hand is slow, and it is not reproducible, because the model exists as a set of files and a set of clicks rather than as a program.

In FloPy the same model is a script. The MODFLOW 6 quick start in the readme shows the whole arc in one block: create a simulation object with a workspace and an executable name, attach the packages, define the grid and the flow package, set a constant head boundary at two opposite corners, write the simulation, run it, read the head and budget output back, and then plot.

```python
import flopy
ws = './mymodel'
name = 'mymodel'
sim = flopy.mf6.MFSimulation(sim_name=name, sim_ws=ws, exe_name='mf6')
tdis = flopy.mf6.ModflowTdis(sim)
ims = flopy.mf6.ModflowIms(sim)
gwf = flopy.mf6.ModflowGwf(sim, modelname=name, save_flows=True)
dis = flopy.mf6.ModflowGwfdis(gwf, nrow=10, ncol=10)
ic = flopy.mf6.ModflowGwfic(gwf)
npf = flopy.mf6.ModflowGwfnpf(gwf, save_specific_discharge=True)
chd = flopy.mf6.ModflowGwfchd(gwf, stress_period_data=[[(0, 0, 0), 1.],
                                                       [(0, 9, 9), 0.]])
budget_file = name + '.bud'
head_file = name + '.hds'
oc = flopy.mf6.ModflowGwfoc(gwf,
                            budget_filerecord=budget_file,
                            head_filerecord=head_file,
                            saverecord=[('HEAD', 'ALL'), ('BUDGET', 'ALL')])
sim.write_simulation()
sim.run_simulation()

head = gwf.output.head().get_data()
bud = gwf.output.budget()
```

The naming follows the MODFLOW 6 package structure, so a ModflowGwfnpf object is the NPF package and a ModflowGwfic object is the IC package. Learning FloPy is largely learning the package names, which is a curve that flattens quickly if you already know the model.

## The model names, and the two axes of the API

The supported model list is broad, and it covers both the flow solver and the transport and pathline tools.

The MODFLOW family is supported: MODFLOW 6, MODFLOW-2005, MODFLOW-NWT, MODFLOW-USG and MODFLOW-2000. The other supported MODFLOW-based models are MODPATH in version 6 and 7, MT3DMS, MT3D-USGS and SEAWAT. So the same script can build a flow model, run a particle tracking model, run a solute transport model and run a variable density seawater model.

The API has two halves that meet in the middle. The model builder side, the flopy.mf6 namespace in the example, constructs the packages and writes the input files. The output side reads what the model wrote, through gwf.output.head().get_data() and gwf.output.budget() in the example, and then post-processes it.

The post-processing step is where the value compounds, because the output objects are not raw arrays but something you can query. In the example, the specific discharge array is pulled out of the budget file by its text identifier and then converted to per-cell vectors with flopy.utils.postprocessing.get_specific_discharge, which is a computation you would otherwise write against the raw MODFLOW output format.

The visualisation side is a third layer. flopy.plot.PlotMapView gives a map view of the grid, on which you can plot an array, draw the grid, add contours at chosen levels and overlay a vector field, all in the same call chain. The readme's example ends with exactly that: the head field plotted, the grid drawn in white, contour lines at 0.2 through 0.8, and the normalised specific discharge vectors on top. That last combination, a field, its contours and its gradient, is the standard way to sanity check a groundwater model, and having it in three lines is what makes a script useful.

## The dependency split, and the code generation group

The packaging is unusually thoughtful for a scientific package, and the pyproject.toml is worth reading.

The required dependencies are three: numpy with a floor of 1.20.3 and a ceiling below 3.0, matplotlib at 1.4.0 or newer, and pandas at 2.0.0 or newer. That is it. FloPy itself pulls in nothing heavy, so the base install stays small and the scientific stack it depends on is the one a hydrologist already has.

Everything else is optional, and the optional group is long. It includes the geospatial and raster stack, affine, fiona, geopandas, pyproj, pyshp, rasterio, rasterstats, shapely and xmipy, the netCDF and HDF readers netcdf4 and h5py, the visualisation and machine learning entries pyvista, vtk at 9.4.0 or newer, imageio, scikit-learn and scipy, plus pooch for data fetching, descartes, geojson and GitPython. pymetis is marked as not for Windows.

Then there is a separate codegen group, which is the part that reveals how FloPy is maintained. It contains Jinja2, boltons, toml and tomli-w, and modflow-devtools at 1.7.0 or newer with 1.9.0 excluded. Those are the tools that generate the model packages from the MODFLOW source definitions, which means the large family of ModflowGwf* classes is generated code rather than hand written, and the package reflects the MODFLOW 6 input specification rather than being a reimplementation of it.

The exclusion of one specific modflow-devtools version is the kind of detail that tells you the project tracks upstream dependencies deliberately. So is the classification as Development Status 5, Production/Stable, with an Intended Audience of Science/Research and Python 3.11 through 3.14 supported.

## Installing, and where the model binaries come from

Installation is through conda-forge or pip:

```bash
    conda install -c conda-forge flopy
```

```bash
    pip install flopy
```

The requirement is Python 3.11 or newer, and the documentation distinguishes the stable release from the current release candidate, with the latest release and the latest documentation hosted separately on readthedocs. The release candidate can also be installed from the git repository using the instructions in the readme, which matters if you need a fix that has not shipped.

The interesting part is what comes after installation. FloPy does not bundle the MODFLOW executable, because the solver is a separate project with its own releases, so there is a command to fetch it:

```bash
    get-modflow :
```

That is the missing piece for anyone starting from scratch, since a script that calls run_simulation needs a binary named mf6, or mf6.exe, to be on the path. The readme links the get_modflow documentation for more information, and the MODFLOW 6 example problems are linked separately as a way to see FloPy used to create, run and post-process a real model.

The project is a USGS effort. The authors are listed as the FloPy Team with a usgs.gov address, and the maintainer is listed individually, also with a usgs.gov address. The licence in the pyproject is CC0-1.0, which is about as permissive as a licence gets and is unusual for scientific software, and the repository carries a CITATION.cff file for citation metadata.

The default branch is develop, and the version in the readme is 3.12.0.dev0, with recent releases 3.11.0 from 2026-09-03, 3.10.0 from 2026-02-06 and 3.9.5 from 2025-10-01, and the last push was on 2026-10-19.

## The project asks you to use the forum, not the issue tracker

The questions section of the readme is short and unusually direct, and it is worth knowing before you file anything.

FloPy usage has been growing rapidly, and as the number of users has increased, so has the number of questions about how to use it. The project asks users to carefully consider the nature of their problem and seek help in the appropriate manner. General support questions are not to go into GitHub issues, because the project wants to keep issues for bug reports and feature requests, and the readme points at the Discussions area on the repository, with Stack Overflow and the MODFLOW google group as other options, though it says neither of those is currently as active as Discussions.

The stated consequence is blunt: all issues that are requests for general support will be systematically closed and people redirected to Stack Overflow or the MODFLOW google group. Stack Overflow questions should be tagged flopy.

For a package with this much surface area, that is a defensible policy rather than an unfriendly one. A groundwater model that does not converge has a dozen plausible causes, and the answer is usually a modelling question rather than a bug, so the issue tracker is the wrong place for it. The readme also points general modelling issues at the MODFLOW Users Group forum.

The rest of the project resources are listed as well. There are FloPy tutorials and scripts demonstrating running and post-processing models, example notebooks demonstrating the pre- and post-processing capabilities across a variety of MODFLOW-based models, a supported packages list in docs/supported_packages.md, a table of supported and proposed model checks in docs/model_checks.md, and a summary of changes in each version in docs/version_changes.md. That last one matters for anyone upgrading, since the package is large and the API does move between versions.

## Conclusion

Adopt FloPy if you are doing groundwater modelling and want models that are reproducible, version controlled and scriptable rather than assembled by hand in a desktop GUI, especially if you need to run the same model across many parameter sets. Do not adopt it if your workflow is one-off manual calibration in a graphical tool, because the modelling knowledge it encodes is a large part of what it costs. Before you commit, check the supported packages list for your model, run the MODFLOW 6 example problems, and decide which optional dependencies you actually need, since the optional group is large and includes heavy geospatial and visualisation packages.

## FAQ

### What is FloPy?

FloPy is a Python package to create, run and post-process MODFLOW-based models. It lets you build a groundwater model, execute it and read and visualise the results from a script rather than through a graphical model editor, making the whole workflow reproducible and versionable.

### Which models does FloPy support?

MODFLOW 6, MODFLOW-2005, MODFLOW-NWT, MODFLOW-USG and MODFLOW-2000, plus the MODFLOW-based models MODPATH version 6 and 7, MT3DMS, MT3D-USGS and SEAWAT.

### How do I install FloPy and the MODFLOW executable?

Install FloPy with conda install -c conda-forge flopy or pip install flopy, which needs Python 3.11 or newer. FloPy does not bundle the solver, so you fetch the MODFLOW programs separately with the get-modflow command.

### What are FloPy's required dependencies?

Three: numpy with a floor of 1.20.3 and a ceiling below 3.0, matplotlib at 1.4.0 or newer, and pandas at 2.0.0 or newer. The geospatial, raster, netCDF, visualisation and machine learning packages are all in an optional group, and a separate codegen group holds the tools that generate the model packages.

### Where should I ask a question about FloPy?

Not in GitHub issues, since the project states it will close all issues that are general support requests and redirect people to Stack Overflow, tagged flopy, or the MODFLOW google group. Discussions on the repository is stated to be the most active option, and the MODFLOW Users Group forum is the place for general modelling questions.

## Sources

- [Issues](https://github.com/modflowpy/flopy/issues)
- [modflowpy/flopy on GitHub](https://github.com/modflowpy/flopy)
- [Project website](https://flopy.readthedocs.io)
- [README](https://github.com/modflowpy/flopy/blob/develop/README.md)
- [Releases](https://github.com/modflowpy/flopy/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/modflowpy-flopy