---
description: Install MatMelt with the installer script or with pip, and verify it runs.
---

# Installation

MatMelt needs **Python 3.10 or newer**. It installs into its own environment and
requires no root access.

:::{admonition} Version 0.2.0 is not on PyPI yet
:class: important

MatMelt was renamed from `materials-cli` at 0.2.0, and the `matmelt`
distribution has not been published yet. Until it is, `pip install matmelt`
will not resolve — install **from the repository** as shown below.

The last published release under the old name is `materials-cli` 0.1.1, which
pre-dates the rename. `pip install --upgrade materials-cli` cannot cross over to
the new name: PyPI treats them as unrelated projects, so a fresh install is
required either way.
:::

## The installer script

The installer builds a dedicated virtual environment, installs MatMelt into it,
and links a `matmelt` launcher into `~/.local/bin`. It never uses `sudo`, never
touches your system Python, and re-running it is the upgrade-and-repair path.

```console
$ git clone https://github.com/Quantum-ARISE-Acad/qa-materials-cli.git
$ cd qa-materials-cli
$ ./install.sh
```

After release, the one-liner form works from anywhere:

```console
$ curl -fsSL https://raw.githubusercontent.com/Quantum-ARISE-Acad/qa-materials-cli/main/install.sh | bash
```

The script understands four environment overrides:

`MATMELT_SPEC`
: What pip installs. Defaults to `matmelt` from PyPI; a `git+https://…` URL or
  a path to a local checkout works identically, which is how pre-release
  installs are done. Whatever you pass is recorded and becomes what
  `matmelt update` re-installs from later.

`MATMELT_HOME`
: Install root. Default `~/.local/share/matmelt`.

`MATMELT_BIN`
: Where the launcher is linked. Default `~/.local/bin`.

`MATMELT_PYTHON`
: The interpreter used to build the environment. Default `python3`.

So a pre-release install from a checkout is:

```console
$ MATMELT_SPEC="$PWD" ./install.sh
```

If `~/.local/bin` is not on your `PATH`, the script says so and prints the line
to add to your shell profile.

## With pip

If you would rather manage the environment yourself:

```console
$ python3 -m venv ~/matmelt-venv
$ ~/matmelt-venv/bin/pip install git+https://github.com/Quantum-ARISE-Acad/qa-materials-cli.git
```

and after release, simply:

```console
$ ~/matmelt-venv/bin/pip install matmelt
```

## The `[compute]` extra

There is an optional extra that installs the scientific stack alongside the
tool:

```console
$ ~/matmelt-venv/bin/pip install "matmelt[compute]"
```

It is a **convenience alias, not a requirement** — it installs SMACT, PyXtal and
`mace-torch` (which brings ASE and PyTorch with it) into that same environment.
Read {doc}`dependencies` before using it: putting several gigabytes of PyTorch
into the tool's own environment is often *not* what you want, and pointing each
stage at an environment you already have is usually better.

## Verify

```console
$ matmelt --version
matmelt 0.2.0
```

```console
$ matmelt --help
```

The help text lists every command: `init`, `doctor`, `run`, `status`, `retry`,
`results`, `monitor`, `cif` and `update` — all of them, with their flags, in the
{doc}`command reference <../reference/cli>`. When a new version lands, see
{doc}`../how-to/update`.

:::{note}
If you installed with pip into your own environment rather than using the
installer script, replace `matmelt` with `~/matmelt-venv/bin/matmelt` in every
example on this site, or activate the environment first.
:::

Next: {doc}`dependencies` — what the scientific stages need, and how MatMelt
tells you what is missing.
