Skip to content


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.


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.


Arch Linux

sudo pacman -S asciinema


sudo apt install asciinema


sudo dnf install asciinema


sudo emerge -av asciinema

NixOS / Nix

nix-env -i asciinema
nix-shell -p asciinema
environment.systemPackages = [
home.packages = [


sudo zypper install asciinema


sudo apt install asciinema

David Adam (zanchey) maintains asciinema PPA.

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


brew install asciinema
sudo port selfupdate && sudo port install asciinema
nix-env -i asciinema


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


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

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
docker run --rm -it

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

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


If you plan to upload your recordings to 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 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 rec demo.cast
docker run --rm -it -v "$PWD:/root" --workdir=/data 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 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
root@6689517d99a1:~# apt install foobar
root@6689517d99a1:~# asciinema rec demo.cast
docker run --rm -it --entrypoint=/bin/bash
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 \ rec

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
cd asciinema
git checkout main
python3 -m asciinema --version