Skip to content

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.

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-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

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

brew install asciinema

sudo port selfupdate && sudo port install asciinema

nix-env -i asciinema

FreeBSD

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:

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).

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

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

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

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:

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:

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