Skip to content

Installation

asciinema CLI can be installed in the following ways:

  • using a package manager on Linux, macOS, and FreeBSD - search for a package named asciinema,
  • downloading a pre-built, static binary of the latest version from the releases page,
  • using a container image,
  • building from source.

Older versions of asciinema (2.x) can also be obtained as the PyPI package.

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

PyPI

asciinema CLI 2.x 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

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 (run asciinema --help 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

You can build latest development version of asciinema CLI by using Rust's cargo package manager:

cargo install --locked --git https://github.com/asciinema/asciinema

If you'd like 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
cargo run --release -- --help