asciinema is a lightweight tool to record terminal sessions, stream them live, and share them as compact asciicast files. This guide walks you through prerequisites, installation, recording, playback, streaming, and troubleshooting so you can start capturing and sharing your terminal workflows with confidence.
Prerequisites
Before you begin, make sure you have a POSIX-compatible terminal (Linux, macOS, or FreeBSD). Optionally, install Rust and cargo if you plan to build from source.
Check your operating system
uname -s
Linux
This command prints the OS kernel name. It’s used here to confirm you’re on a supported platform.
Verify whether asciinema is already installed
command -v asciinema
/home/user/.cargo/bin/asciinema
command -v returns the path to an executable in your $PATH. If it’s empty, asciinema isn’t installed yet.
Installation (multiple options)
Pick the option that matches your environment: package manager (recommended), Homebrew for macOS, or building from source via cargo. Each command below includes an example output and a brief explanation.
1) Debian / Ubuntu (apt)
sudo apt update
Get:1 http://archive.ubuntu.com/ubuntu focal InRelease Get:2 http://archive.ubuntu.com/ubuntu focal-updates InRelease Fetched 32.1 MB in 3s (10.4 MB/s) Reading package lists... Done
sudo elevates privileges to run package management. Use it because installing system packages requires root.
sudo apt install -y asciinema
Reading package lists... Done Building dependency tree Reading state information... Done The following NEW packages will be installed: asciinema 0 upgraded, 1 newly installed, 0 to remove and 12 not upgraded. Need to get 120 kB of archives. After this operation, 520 kB of additional disk space will be used. Get:1 http://archive.ubuntu.com/ubuntu focal/universe asciinema amd64 2.0.0-1 [120 kB] Fetched 120 kB in 0s (2,044 kB/s) Selecting previously unselected package asciinema. (Reading database ... 180000 files and directories currently installed.) Preparing to unpack .../asciinema_2.0.0-1_amd64.deb ... Unpacking asciinema (2.0.0-1) ... Setting up asciinema (2.0.0-1) ... Processing triggers for man-db (2.9.1-1) ...
This installs the packaged asciinema. The -y flag answers “yes” to prompts; omit if you prefer interactive confirmation.
2) macOS (Homebrew)
brew install asciinema
==> Installing dependencies for asciinema: python@3.9 ==> Installing asciinema 🍺 /usr/local/Cellar/asciinema/2.0.0: 3 files, 120KB, built in 4 seconds
brew installs packages on macOS; this example also installs any required dependency like Python if needed.
3) From source (Rust / cargo) — cross-platform
cargo install --locked --git https://github.com/asciinema/asciinema
Cloning https://github.com/asciinema/asciinema Updating crates.io index Compiling asciinema v3.1.0 (https://github.com/asciinema/asciinema#master) Installing /home/user/.cargo/bin/asciinema Installed package `asciinema v3.1.0` (executable `asciinema`) to /home/user/.cargo/bin
Use this to get the latest release directly from the repository. cargo install compiles and places the binary in $HOME/.cargo/bin, so ensure that path is in your $PATH.
Setup and configuration
Ensure the binary is on your PATH
echo $PATH
/home/user/.cargo/bin:/usr/local/bin:/usr/bin:/bin
This confirms where your shell looks for executables. If /home/user/.cargo/bin is missing, add it to your shell profile (e.g., ~/.bashrc or ~/.zshrc).
Generate man pages and shell completions (optional)
ASCIINEMA_GEN_DIR=/tmp/asciinema_docs cargo build --release
Compiling asciinema v3.1.0 Finished release [optimized] target(s) in 18.23s Man pages generated in /tmp/asciinema_docs/man/ Completions generated in /tmp/asciinema_docs/completion/
Setting ASCIINEMA_GEN_DIR tells the build system where to place generated docs and completion scripts.
Basic usage: recording, playback, and uploading
The typical workflow is: record a session to a .cast asciicast file, play it locally, and optionally upload or embed it.
Record a session
asciinema rec demo.cast
asciinema: recording Press or type "exit" to finish. asciinema: saving to demo.cast... done
asciinema rec demo.cast starts recording the terminal session and saves the result in demo.cast. Use Ctrl-D or type exit to stop recording. The command captures text output and timing metadata (asciicast v3).
Verify the recording file
ls -lh demo.cast
-rw-r--r-- 1 user user 8.1K Feb 10 12:34 demo.cast
This confirms the recording file exists and shows its size and timestamp.
Play back a recording in the terminal
asciinema play demo.cast
Replaying session from demo.cast $ pwd /home/user $ ls -la total 28 drwxr-xr-x 4 user user 4096 Feb 10 12:33 . drwxr-xr-x 3 user user 4096 Feb 10 11:00 .. -rw-r--r-- 1 user user 120 Feb 10 12:34 demo.cast
Playback recreates the original terminal timing and output. Use this to review your session or demonstrate commands to others.
Upload a recording to asciinema.org (optional)
asciinema upload demo.cast
Uploading demo.cast... Upload successful: https://asciinema.org/a/123456
This uploads to the asciinema.org server and returns a shareable URL. Use it to embed sessions in docs or blogs.
Live streaming
You can stream sessions either locally (HTTP server) or via a relay (asciinema server).
Start a local stream
asciinema stream -l
Starting local web server on http://127.0.0.1:8080 Stream ID: local/abc123 Waiting for players... (press Ctrl-C to stop)
asciinema stream -l serves the live session locally so viewers on your network can watch in real time.
Stream via a relay (public server)
asciinema stream -r
Relaying via https://asciinema.org Stream token: r_ABC123def Shareable URL: https://asciinema.org/s/abc123 Waiting for connections...
-r uses a relay (like asciinema.org) to distribute a live stream to remote viewers.
Verification
Check asciinema version
asciinema --version
asciinema 3.1.0
This confirms the installed version. Keep the tool up-to-date for the latest features and fixes.
Locate the binary
which asciinema
/home/user/.cargo/bin/asciinema
which shows the path to the executable used by your shell. If it’s not the expected location, adjust your $PATH.
Troubleshooting
Common issue: asciinema not found after cargo install
asciinema --version
bash: asciinema: command not found
If your shell can’t find the command after a cargo install, it usually means $HOME/.cargo/bin is not in $PATH. Add the line below to your shell profile and re-open the terminal:
export PATH="$HOME/.cargo/bin:$PATH"
echo $PATH /home/user/.cargo/bin:/usr/local/bin:/usr/bin:/bin
Adding the export ensures the path persists; echo $PATH confirms the change.
Permission denied when binding low-numbered ports for stream
asciinema stream -l -p 80
Failed to bind to port 80: Permission denied
Ports below 1024 usually require root. Use a higher port (e.g., 8080), or run a reverse proxy. Avoid running asciinema as root; instead, choose a non-privileged port.
Recording shows “exit” printed at end
asciinema rec demo.cast ... exit asciinema: saving to demo.cast... done
asciinema records the commands you type (including exit). This is normal because the session captured includes your input and timing. If you want to avoid showing the final exit command, manually clear the terminal before ending, or post-process the .cast file.
Uninstalling
sudo apt remove --purge asciinema
Reading package lists... Done Removing asciinema (2.0.0-1) ... Processing triggers for man-db (2.9.1-1) ...
Use your package manager or cargo uninstall asciinema if you installed via cargo.
Advanced: embedding and server/self-hosting
Recordings can be embedded in blog posts or docs with the asciinema web player (the uploaded URL from asciinema upload provides embeddable markup). If you need private hosting or larger-scale streaming, consider running your own asciinema server or using available server packages; consult the official docs for deployment details.
Troubleshooting checklist
- Confirm asciinema –version returns the expected version.
- Ensure $HOME/.cargo/bin (or package-managed path) is in $PATH.
- Use non-privileged ports for local streaming (>= 1024).
- If uploads fail, check network connectivity and proxy settings.
Conclusion
asciinema makes it easy to record terminal sessions, produce compact asciicast files, and share or embed terminal recordings. Whether you need quick screencasts for documentation, reproducible demos, or live terminal recording streams, asciinema is a lightweight, flexible solution. Try the commands in this guide to start capturing your workflow today.
