# Installing poezio

Warning

Python 3.11 or above is required. To install it on a distribution that doesn’t provide it, see pyenv.

## poezio in the GNU/Linux distributions

As far as I know, Poezio is available in the following distributions, you just have to install it by using the package manager of the distribution, if you’re using one of these.

- Archlinux: poezio and poezio-git packages are in the AUR (use your favourite AUR wrapper to install them)

- Gentoo: net-im/poezio

- Fedora: There is an up-to-date package in the repos since F19.

- CentOS: Poezio is available in EPEL repositories since CentOS 8.

- Flatpak: A stable package is provided on flathub.

- Debian: A stable package is provided since buster thanks to debacle.

- Nix (and NixOS): The last stable version of poezio is available in the unstable branch of nixpkgs. Use `nix-env -f "<nixpkgs>" -iA poezio` to install poezio for the current user.

- OpenBSD: a poezio port is available

- Guix: Poezio can be obtained with Guix on any GNU/Linux distribution. To install poezio in default user-profile: `guix install poezio`. To try poezio without installation: `guix environment --pure --ad-hoc poezio`.

(If another distribution provides a poezio package, please tell us and we will add it to the list)

Thank to all the maintainers who took time to make and maintain those packages!

## Install from source

### Stable version

Stable version packages are available in standalone (dependencies provided) and poezio-only packages (both with prebuilt html doc for convenience).

Those versions are also available on pypi (using uv, for example), and it is recommended to install them this way if you absolutely want to install poezio and your distribution provides no package.

### Development version

The stable versions of poezio are more like snapshots of states of development we deem acceptable. There is always an incentive to use the development version, like new features, bug fixes, and more support. Therefore, you might want to use the git version.

    git clone https://codeberg.org/poezio/poezio
    cd poezio

#### General

Poezio is a python3.11 (and above)-only application, so you will first need that.

Note

If not building a package for a distribution, use of the `uv` tool is highly recommended.

Packages required for building poezio and deps:

- make

- gcc

- python3-devel (or equivalent)

- python3-setuptools

- (for slixmpp) maturin and rustc/cargo

Poezio only needs slixmpp for its base functionality, and building slixmpp from source requires the maturin build backend, as well as a rust compiler.

#### Users

uv takes care of everything, so building and installing all required packages is simple as:

    uv sync --all-groups --all-extras

Then you can just run it.

Note

We provide an `update.sh` script that creates a virtualenv and downloads all the required and optional dependencies inside it. we recommend using it with the git version of poezio, in order to keep everything up-to-date.

#### Packagers

As long as you have a slixmpp packaged, it should be straightforward to build a package for poezio using the standard facilities:

    python3 -m build

### Running

If you didn’t install poezio, you can run it from the source directory with:

    ./launch.sh
    # Or
    uv run poezio

## Docker images

poezio is available on the docker hub in the poezio/poezio repository in which `poezio/poezio:latest` is the latest built git version, and stable versions are tagged with their numbers. The image is based off alpine linux and we tried to keep the image size to a minimum (<100MiB).

You can therefore just fetch the images with docker pull:

    docker pull poezio/poezio

In order to run poezio with non-temporary config and logs, and to have the right colors, you have to share the `TERM` env var and some directories that should be created beforehand:

    mkdir -p ~/.config/poezio ~/.local/share/poezio
    docker run -it -e TERM -v ~/.config/poezio:/home/poezio-user/.config/poezio -v ~/.local/share/poezio:/home/poezio-user/.local/share/poezio poezio/poezio

If you don’t trust images distributed on the docker hub, you can rebuild the image from the Dockerfile at the root of the git repository.