# Installation


# Agentic Installation

An agent can be utilized to perform all the required and recommended steps as indicated on this page automatically. Please install the package skills using the agent framework of your choice. Create an empty directory, point you agent to this directory and prompt for example:

``` markdown
Please install matr1x as described in the matr1x-install skill.
```

If you have problems installing the skills, please point the agent to

``` markdown
https://andythomas.github.io/matr1x/.well-known/agent-skills/matr1x-install/SKILL.md
```


# Basic Installation

Please use [Github Desktop](https://desktop.github.com/download/) to clone the repository. We recommend to install uv, because it simplifies the installation and downloads the package versions we utilize for testing. Then, two more steps are required for the installation:

1.  Sychronize uv in the cloned directory
2.  Activate the virtual environment

<span class="gd-details-chevron" aria-hidden="true"></span><img src="data:image/svg+xml;base64,PHN2ZyBzdHlsZT0iaGVpZ2h0OjFlbTt3aWR0aDoxZW07dmVydGljYWwtYWxpZ246LTAuMTI1ZW07Zm9udC1zaXplOmluaGVyaXQ7b3ZlcmZsb3c6dmlzaWJsZTtwb3NpdGlvbjpyZWxhdGl2ZTsiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgdmlld2JveD0iMCAwIDI0IDI0IiBmaWxsPSJub25lIiBzdHJva2U9ImN1cnJlbnRDb2xvciIgc3Ryb2tlLSBzdHJva2UtbGluZWNhcD0icm91bmQiIHN0cm9rZS1saW5lam9pbj0icm91bmQiIGNsYXNzPSJnZC1kZXRhaWxzLWljb24iIGFyaWEtaGlkZGVuPSJ0cnVlIj48cGF0aCBkPSJNMTUgMTRjLjItMSAuNy0xLjcgMS41LTIuNSAxLS45IDEuNS0yLjIgMS41LTMuNUE2IDYgMCAwIDAgNiA4YzAgMSAuMiAyLjIgMS41IDMuNS43LjcgMS4zIDEuNSAxLjUgMi41IiAvPjxwYXRoIGQ9Ik05IDE4aDYiIC8+PHBhdGggZD0iTTEwIDIyaDQiIC8+PC9zdmc+" class="gd-details-icon" />Always keep uv updated.


In case of errors during the installation or unexpected behavior at the first run, always keep `uv` [updated](https://docs.astral.sh/uv/getting-started/installation/#upgrading-uv).


- <a href="" id="tabset-1-1-tab" class="nav-link active" data-bs-toggle="tab" data-bs-target="#tabset-1-1" role="tab" aria-controls="tabset-1-1" aria-selected="true">Windows</a>
- <a href="" id="tabset-1-2-tab" class="nav-link" data-bs-toggle="tab" data-bs-target="#tabset-1-2" role="tab" aria-controls="tabset-1-2" aria-selected="false">MacOS</a>
- <a href="" id="tabset-1-3-tab" class="nav-link" data-bs-toggle="tab" data-bs-target="#tabset-1-3" role="tab" aria-controls="tabset-1-3" aria-selected="false">Linux/Unix</a>


1.  Follow the [uv installation](https://docs.astral.sh/uv/getting-started/installation/) procedure.
2.  Execute `uv sync`
3.  Execute `.venv\Scripts\activate.bat` in a command prompt or PowerShell window.


The system Python version is quite old (3.9 in Sequoia) and cannot be used to install the packages.

1.  Follow the [uv installation](https://docs.astral.sh/uv/getting-started/installation/) procedure.
2.  Execute `uv sync`
3.  Execute `source .venv/bin/activate`


The package can be installed on Linux systems (well tested) and also on BSD systems (not tested regularly) and likely other Posix compliant systems. We recommend using a virtual environment. First, make sure you have the required system packages installed.

``` bash
sudo apt install qt6-base-dev
```

Then, continue the basic installation:

1.  Follow the [uv installation](https://docs.astral.sh/uv/getting-started/installation/) procedure.
2.  Execute `uv sync`
3.  Execute `source .venv/bin/activate`


If an optional feature is required for your setup use `uv sync --extra <FEATURE>` instead.


# Desktop Integration

After the installation, any application launch will perform the desktop integration, i.e. provide application icons, start menu entries and such. For example, please execute

- `matrix-preview`

A command line tool can carry out the integration as well: Please start `matrix-di` for integration and `matrix-di -u` for removal.

`matrix-script` might need a few moments at the first start to download the editor assets.


# Overview of Recommended Options

An overview of recommended options for the specific platforms is given in the following table. In most cases we recommend an installation into a dedicated virtual environment. Most Mac and Linux systems require the virtual environment, while Windows does not require it.

| Platform   | Python distribution | Virtual environment  | editable installation |
|------------|---------------------|----------------------|-----------------------|
| Windows    | uv recommended      | weakly recommended   | Yes                   |
| Linux/Unix | uv or system Python | strongly recommended | Yes                   |
| Mac OS     | uv                  | required             | Yes                   |