---
description: Upgrade MatMelt in place with matmelt update, and what to do when it tells you it cannot.
---

# Update MatMelt

```console
$ matmelt update
```

```text
Successfully installed matmelt-0.2.0
MatMelt updated (version 0.2.0).
```

`update` re-runs the install that produced this environment. It does not guess:
`install.sh` records what it installed from, and `update` reads that record back.

The version is reported by a **fresh interpreter**, because the process running
the update is still holding the old code. If the number surprises you, run
`matmelt --version` afterwards.

Your workspaces are untouched — `update` changes the installation, never a run.

## When it refuses

`update` only manages installations it can manage, and says which case you are
in:

```text
update: this environment was not set up by install.sh (no matmelt.spec in
~/matmelt/.venv) -- update it the way it was installed: 'pip install --upgrade
matmelt' for a pip install, 'git pull' + 'pip install -e .' for a dev checkout.
```

Exit `1`, nothing changed. Follow whichever half applies:

| How you installed | How to update |
|---|---|
| `install.sh` | `matmelt update` |
| `pip install matmelt` | `pip install --upgrade matmelt` |
| `git clone` + `pip install -e .` | `git pull`, then `pip install -e .` |

It also refuses when the interpreter is a system Python, rather than upgrading
packages your operating system manages.

## Installing somewhere else

`install.sh` puts MatMelt in a dedicated virtual environment and links a
launcher onto your `PATH`. Re-running it repairs or upgrades an existing
install, and it takes environment overrides:

```console
$ MATMELT_HOME=~/opt/matmelt MATMELT_BIN=~/bin bash install.sh
```

```text
Installing MatMelt
  spec:     matmelt
  venv:     ~/opt/matmelt/venv
  launcher: ~/bin/matmelt
...
Installed: matmelt 0.2.0
Next: cd to a working directory and run 'matmelt init'.
```

`MATMELT_SPEC` controls what is installed — the PyPI name by default, or a git
URL or local checkout path when you want a specific version. Whatever you pass
is what `matmelt update` will use later, so installing from a checkout keeps
updating from that checkout.

If the launcher directory is not on your `PATH`, the installer says so and
prints the line to add.

## After updating

```console
$ matmelt --version
$ matmelt doctor
```

`doctor` re-checks the environment against your config, which is what you want
after a version change — see {doc}`doctor`.

## Related

- {doc}`../getting-started/installation` — the install paths in full.
- [`CHANGELOG.md`](https://github.com/Quantum-ARISE-Acad/qa-materials-cli/blob/main/CHANGELOG.md)
  for what changed between versions.
