<commit_before># Upgrading Synapse

Before upgrading check if any special steps are required to upgrade from
the version you currently have installed to the current version of
Synapse. The extra instructions that may be required are listed later in
this document.

-   Check that your versions of Python and PostgreSQL are still
    supported.

    Synapse follows upstream lifecycles for [Python](https://endoflife.date/python) and
    [PostgreSQL](https://endoflife.date/postgresql), and removes support for versions
    which are no longer maintained.

    The website <https://endoflife.date> also offers convenient
    summaries.

-   If Synapse was installed using [prebuilt
    packages](setup/installation.md#prebuilt-packages), you will need to follow the
    normal process for upgrading those packages.

-   If Synapse was installed using pip then upgrade to the latest
    version by running:

    ```bash
    pip install --upgrade matrix-synapse
    ```

-   If Synapse was installed from source, then:

    1.  Obtain the latest version of the source code. Git users can run
        `git pull` to do this.

    2.  If you're running Synapse in a virtualenv, make sure to activate it before
        upgrading. For example, if Synapse is installed in a virtualenv in `~/synapse/env` then
        run:

        ```bash
        source ~/synapse/env/bin/activate
        pip install --upgrade .
        ```
        Include any relevant extras between square brackets, e.g. `pip install --upgrade ".[postgres,oidc]"`.

    3.  If you're using `poetry` to manage a Synapse installation, run:
        ```bash
        poetry install
        ```
        Include any relevant extras with `--extras`, e.g. `poetry install --extras postgres --extras oidc`.
        It's probably easiest to run `poetry install --extras all`.

    4.  Restart Synapse:

        ```bash
        synctl restart
        ```

To check whether your update was successful, you can check the running
server version with:

```bash
# you may need to replace 'localhost:8008' if synapse is not configured
# to listen on port 8008.

curl http://localhost:8008/_synapse/admin/v1/server_version
```

## Rolling back to older versions

Rolling back to previous releases can be difficult, due to database
schema changes between releases. Where we have been able to test the
rollback process, this will be noted below.

In general, you will need to undo any changes made during the upgrade
process, for example:

-   pip:

    ```bash
    source env/bin/activate
    # replace `1.3.0` accordingly:
    pip install matrix-synapse==1.3.0
    ```

-   Debian:

    ```bash
    # replace `1.3.0` and `stretch` accordingly:
    wget https://packages.matrix.org/debian/pool/main/m/matrix-synapse-py3/matrix-synapse-py3_1.3.0+stretch1_amd64.deb
    dpkg -i matrix-synapse-py3_1.3.0+stretch1_amd64.deb
    ```

# Upgrading to v1.64.0

## Changes to the event replication streams

Synapse now includes a flag indicating if an event is an outlier when
replicating it to other workers. This is a forwards- and backwards-incompatible
change: v1.63 and workers cannot process events replicated by v1.64 workers, and
vice versa.

Once all workers are upgraded to v1.64 (or downgraded to v1.63), event
replication will resume as normal.

## frozendict release

[frozendict 2.3.3](https://github.com/Marco-Sulla/python-frozendict/releases/tag/v2.3.3)
has recently been released, which fixes a memory leak that occurs during `/sync`
requests. We advise server administrators who installed Synapse via pip to upgrade
frozendict with `pip install --upgrade frozendict`. The Docker image
`matrixdotorg/synapse` and the Debian packages from `packages.matrix.org` already
include the updated library.

# Upgrading to v1.62.0<commit_msg>Add upgrade notes<commit_after># Upgrading Synapse

Before upgrading check if any special steps are required to upgrade from
the version you currently have installed to the current version of
Synapse. The extra instructions that may be required are listed later in
this document.

-   Check that your versions of Python and PostgreSQL are still
    supported.

    Synapse follows upstream lifecycles for [Python](https://endoflife.date/python) and
    [PostgreSQL](https://endoflife.date/postgresql), and removes support for versions
    which are no longer maintained.

    The website <https://endoflife.date> also offers convenient
    summaries.

-   If Synapse was installed using [prebuilt
    packages](setup/installation.md#prebuilt-packages), you will need to follow the
    normal process for upgrading those packages.

-   If Synapse was installed using pip then upgrade to the latest
    version by running:

    ```bash
    pip install --upgrade matrix-synapse
    ```

-   If Synapse was installed from source, then:

    1.  Obtain the latest version of the source code. Git users can run
        `git pull` to do this.

    2.  If you're running Synapse in a virtualenv, make sure to activate it before
        upgrading. For example, if Synapse is installed in a virtualenv in `~/synapse/env` then
        run:

        ```bash
        source ~/synapse/env/bin/activate
        pip install --upgrade .
        ```
        Include any relevant extras between square brackets, e.g. `pip install --upgrade ".[postgres,oidc]"`.

    3.  If you're using `poetry` to manage a Synapse installation, run:
        ```bash
        poetry install
        ```
        Include any relevant extras with `--extras`, e.g. `poetry install --extras postgres --extras oidc`.
        It's probably easiest to run `poetry install --extras all`.

    4.  Restart Synapse:

        ```bash
        synctl restart
        ```

To check whether your update was successful, you can check the running
server version with:

```bash
# you may need to replace 'localhost:8008' if synapse is not configured
# to listen on port 8008.

curl http://localhost:8008/_synapse/admin/v1/server_version
```

## Rolling back to older versions

Rolling back to previous releases can be difficult, due to database
schema changes between releases. Where we have been able to test the
rollback process, this will be noted below.

In general, you will need to undo any changes made during the upgrade
process, for example:

-   pip:

    ```bash
    source env/bin/activate
    # replace `1.3.0` accordingly:
    pip install matrix-synapse==1.3.0
    ```

-   Debian:

    ```bash
    # replace `1.3.0` and `stretch` accordingly:
    wget https://packages.matrix.org/debian/pool/main/m/matrix-synapse-py3/matrix-synapse-py3_1.3.0+stretch1_amd64.deb
    dpkg -i matrix-synapse-py3_1.3.0+stretch1_amd64.deb
    ```

# Upgrading to v1.64.0

## Deprecation of the ability to delegate e-mail verification to identity servers

Synapse v1.66.0 will remove the ability to delegate the tasks of verifying email address ownership, and password reset confirmation, to an identity server.

If you require your homeserver to verify e-mail addresses or to support password resets via e-mail, please configure your homeserver with SMTP access so that it can send e-mails on its own behalf.
[Consult the configuration documentation for more information.](https://matrix-org.github.io/synapse/latest/usage/configuration/config_documentation.html#email)

The option that will be removed is `account_threepid_delegates.email`.


## Changes to the event replication streams

Synapse now includes a flag indicating if an event is an outlier when
replicating it to other workers. This is a forwards- and backwards-incompatible
change: v1.63 and workers cannot process events replicated by v1.64 workers, and
vice versa.

Once all workers are upgraded to v1.64 (or downgraded to v1.63), event
replication will resume as normal.

## frozendict release

[frozendict 2.3.3](https://github.com/Marco-Sulla/python-frozendict/releases/tag/v2.3.3)
has recently been released, which fixes a memory leak that occurs during `/sync`
requests. We advise server administrators who installed Synapse via pip to upgrade
frozendict with `pip install --upgrade frozendict`. The Docker image
`matrixdotorg/synapse` and the Debian packages from `packages.matrix.org` already
include the updated library.

# Upgrading to v1.62.0
{'fraction_non_alphanumeric': 0.07683903860160234, 'fraction_numerical': 0.016751638747268753, 'mean_word_length': 3.3431734317343174, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 11, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '569401', 'n_tokens_mistral': 2447, 'n_tokens_neox': 2281, 'n_words': 987}