Installation¶

asciinema CLI is available in most package repositories on Linux, macOS, and FreeBSD. Search for a package named asciinema.

You can also install the PyPI package, use a container image, or run from source.

PyPI¶

asciinema CLI is available on PyPI and can be installed with pipx.

pipxpip

If you have pipx installed:

pipx install asciinema

Alternatively use pip (Python 3 with setuptools required):

python3 -m pip install asciinema

This is a universal installation method for all operating systems, which always provides the latest released version.

Linux¶

Arch Linux¶

sudo pacman -S asciinema

Debian¶

sudo apt install asciinema

Fedora¶

sudo dnf install asciinema

Gentoo¶

sudo emerge -av asciinema

NixOS / Nix¶

nix-envnix-shellNixOS configurationhome-manager

nix-env -i asciinema

nix-shell -p asciinema

/etc/nixos/configuration.nix

environment.systemPackages = [
  pkgs.asciinema
]

~/.config/home-manager/home.nix

home.packages = [
  pkgs.asciinema
]

openSUSE¶

sudo zypper install asciinema

Ubuntu¶

22.04 or newerPPA

sudo apt install asciinema

David Adam (zanchey) maintains asciinema PPA.

sudo apt-add-repository ppa:zanchey/asciinema
sudo apt update
sudo apt install asciinema

macOS¶

HomebrewMacPortsNix

brew install asciinema

sudo port selfupdate && sudo port install asciinema

nix-env -i asciinema

FreeBSD¶

PortsPackages

cd /usr/ports/textproc/py-asciinema && make install

pkg install py39-asciinema

OpenBSD¶

pkg_add asciinema

Container image¶

asciinema OCI container image is based on Ubuntu 22.04 and has the latest version of asciinema recorder pre-installed.

Pull the container:

podmandocker

podman pull ghcr.io/asciinema/asciinema

docker pull ghcr.io/asciinema/asciinema

Container's entrypoint is set to asciinema binary therefore you can run the container with arguments you would normally pass to asciinema command (see Usage for commands and options).

When running the container it's essential to allocate a pseudo-TTY (-t) and keep STDIN open (-i).

podmandocker

podman run --rm -it ghcr.io/asciinema/asciinema

docker run --rm -it ghcr.io/asciinema/asciinema

You can optionally bind-mount config directory (-v):

podmandocker

podman run --rm -it -v "$HOME/.config/asciinema:/root/.config/asciinema" ghcr.io/asciinema/asciinema

docker run --rm -it -v "$HOME/.config/asciinema:/root/.config/asciinema" ghcr.io/asciinema/asciinema

Note

If you plan to upload your recordings to asciinema.org then it's recommended to preserve asciinema config directory between runs, e.g. by bind-mounting it as shown above. This directory stores install ID, which links all recordings uploaded from a given system to your asciinema.org user account.

To be able to save the recordings locally bind-mount your working directory like this:

podmandocker

podman run --rm -it -v "$PWD:/root" --workdir=/data ghcr.io/asciinema/asciinema rec demo.cast

docker run --rm -it -v "$PWD:/root" --workdir=/data ghcr.io/asciinema/asciinema rec demo.cast

There's not much software installed in this image. In most cases you may want to install extra programs before recording. One option is to derive a new image from this one (start your custom Dockerfile with FROM ghcr.io/asciinema/asciinema). Another option is to start the container with /bin/bash as the entrypoint, install extra packages and then start recording with asciinema rec:

podmandocker

podman run --rm -it --entrypoint=/bin/bash ghcr.io/asciinema/asciinema
root@6689517d99a1:~# apt install foobar
root@6689517d99a1:~# asciinema rec demo.cast

docker run --rm -it --entrypoint=/bin/bash ghcr.io/asciinema/asciinema
root@6689517d99a1:~# apt install foobar
root@6689517d99a1:~# asciinema rec demo.cast

With Docker, it's also possible to run the container as a non-root user, which has security benefits. You can specify user and group id at runtime to give the application permission similar to the calling user on your host.

docker run --rm -it \
    --env=ASCIINEMA_CONFIG_HOME="/run/user/$(id -u)/.config/asciinema" \
    --user="$(id -u):$(id -g)" \
    --volume="${HOME}/.config/asciinema:/run/user/$(id -u)/.config/asciinema:rw" \
    --volume="${PWD}:/data:rw" \
    --workdir=/data \
    ghcr.io/asciinema/asciinema rec

Note

Podman has first class support for rootless operation.

From source¶

If none of the above works for you (or you want to modify the code) then clone the git repository and run asciinema CLI straight from the checkout:

git clone https://github.com/asciinema/asciinema.git
cd asciinema
git checkout main
python3 -m asciinema --version