# Troubleshooting

Common issues encountered when using GWexpy and their solutions.

## Start Here

Use this page as a reverse lookup by symptom:

- Install worked for the minimal example, but you now need NDS2 / FrameLIB / other binary dependencies: go back to the {ref}`Installation Guide <conda-environment-recommended-gw-analysis>`.
- The first example from [Quickstart](../tutorials/quickstart.md) does not import or plot cleanly: check the matching issue below, then retry the quick example.
- The environment feels mixed or broken after repeated `pip` and Conda changes: rebuild the dedicated Conda environment from the {ref}`Installation Guide <conda-environment-recommended-gw-analysis>`.

## Installation Issues

### 1. Cannot install `nds2` / `framel`
Binary libraries used in the `[gw]` extra cannot be installed via `pip`.

**Solution:**
Use Conda (Miniforge, etc.) in a dedicated environment, then install GWexpy from PyPI there.
```bash
conda create -n gwexpy python=3.11
conda activate gwexpy
conda install -c conda-forge python-nds2-client python-framel ldas-tools-framecpp
pip install "gwexpy[gw,analysis,fitting]"
```

See also: {ref}`Installation Guide <conda-environment-recommended-gw-analysis>`

### 2. Errors on Apple Silicon (M1/M2/M3) Mac
Some GW analysis packages may be built for Intel (x86_64) and might not work out of the box.

**Solution:**
Native (arm64) support for packages from the `conda-forge` channel is improving. Always ensure you are using the latest versions.
```bash
conda update -c conda-forge --all
```

### 3. Compilation error for `minepy` (MIC calculation)
`pip install minepy` may fail due to C extension compilation issues.

**Solution:**
The automated build script is available only from a source checkout of the GWexpy repository. Clone the repository first, then run:
```bash
python scripts/dev_tools/install_minepy.py
```

If this happened while expanding a minimal install, review the extras guidance in the {ref}`Installation Guide <optional-dependencies-extras>`.

## Plotting & Visualization Issues

### 4. Plots not displaying / `Tcl_AsyncDelete` error
There may be an inconsistency with the Matplotlib backend in Jupyter Notebook or GUI applications.

**Solution:**
Try explicitly specifying the backend:
```python
import matplotlib
matplotlib.use('Qt5Agg')  # or 'Agg', 'TkAgg'
```

### 5. Map (`GeoMap`) not displaying
Verify the installation status of `pygmt` and ensure the GMT (Generic Mapping Tools) binary is in your path.

**Solution:**
We recommend reinstalling `pygmt` via Conda.
```bash
conda install -c conda-forge pygmt
```

If you started from the smallest example in [Quickstart](../tutorials/quickstart.md), note that `pygmt` is optional and is not part of the minimal install.

---

## Still Not Working?

For lightweight bug reports and feature requests, use the
[feedback form](https://forms.gle/c8jJaf9UCs5tb5cC8). For reproducible
technical issues that need public tracking, please report the issue with the
error logs on the GitHub [Issues](https://github.com/tatsuki-washimi/gwexpy/issues)
page. Do not include private data, credentials, or security vulnerability
details in the form or public issues; follow the repository [Security Policy](https://github.com/tatsuki-washimi/gwexpy/security/policy).
Including the following information will help us assist you faster:
* OS Version
* Python Version
* The command executed and the full Traceback