Asciinema

2.4.0 · active · verified Wed Apr 15

Asciinema is a free and open-source command-line tool for recording terminal sessions, sharing them on the web, and replaying them in a terminal or web browser. The PyPI package (version 2.4.0) represents the stable Python-based CLI, which captures terminal output into lightweight text-based `.cast` files. While active development for the core CLI has transitioned to a Rust rewrite (version 3.x, not distributed via PyPI as a Python package), the 2.x Python version remains widely used and maintained.

Common errors

```
asciinema: command not found
```
cause The asciinema command is not installed or not in the system's PATH.

fix Install asciinema using the appropriate package manager for your system, such as 'sudo apt install asciinema' for Debian-based systems or 'brew install asciinema' for macOS.
```
Permission denied
```
cause The user does not have the necessary permissions to execute the asciinema command or write to the specified file location.

fix Ensure you have execute permissions for the asciinema binary and write permissions for the target directory. Use 'chmod +x /path/to/asciinema' to add execute permissions if needed.
```
asciinema: error: unrecognized arguments
```
cause An invalid or unsupported argument was passed to the asciinema command.

fix Review the asciinema command usage by running 'asciinema --help' to see the list of supported commands and options.
```
asciinema: failed to upload recording
```
cause The upload process to asciinema.org failed, possibly due to network issues or authentication problems.

fix Check your internet connection and ensure you are authenticated by running 'asciinema auth'.
```
asciinema: failed to record session
```
cause An error occurred during the recording process, potentially due to terminal incompatibility or other system issues.

fix Ensure your terminal supports asciinema and that there are no conflicting processes. Try recording again or consult the asciinema documentation for troubleshooting tips.

Warnings

breaking Asciinema CLI version 3.x (a complete rewrite in Rust, not this Python package) introduces several breaking changes from 2.x, including a new default asciicast v3 format, required filename for `rec`, and renaming of options like `--stdin` to `--capture-input`, and `--env` to `--capture-env`. If you install 3.x from source or other means, be aware of these changes.
Fix: For 2.x behavior, explicitly specify `--output-format asciicast-v2` if interacting with older tools, or adjust command-line arguments to the new 3.x equivalents. Stick to `asciinema==2.4.0` from PyPI if 2.x behavior is strictly required.
gotcha The `asciinema` PyPI package (v2.x) is designed as a standalone command-line application. While it's written in Python, it's not intended for direct `import` and programmatic control of recording/playback features within custom Python scripts. Attempts to import and use internal modules for this purpose may lead to unexpected behavior or API instability.
Fix: Use `subprocess` module to call `asciinema` commands if you need to integrate its functionality into a Python application, or consider alternative Python libraries if low-level terminal interaction/recording is required programmatically.
deprecated The Python-based `asciinema` CLI (version 2.x, including 2.4.0) is now considered the 'previous generation' by the project maintainers. Primary development for the core `asciinema` CLI has shifted to a Rust rewrite (version 3.x). While 2.x is stable and maintained, new major features are likely to land in the Rust version.
Fix: Users seeking the absolute latest features or ongoing active development for the CLI might consider the Rust-based version (often installed via `cargo` or package managers for 3.x releases), or continue using 2.x for its stability.
gotcha The default configuration file location changed from `$HOME/.asciinema` to `$HOME/.config/asciinema/config`. If you had custom configurations in the old location, they will not be picked up automatically.
Fix: Move your existing configuration file from `$HOME/.asciinema` to `$HOME/.config/asciinema/config`.
gotcha The term 'API token' used in older versions (prior to 2.0) has been renamed to 'install ID'. This ID is generated locally and used to associate recordings with your asciinema.org account for management.
Fix: When performing `asciinema auth` or managing recordings online, be aware that what was previously called an 'API token' is now referred to as an 'install ID'.

Install

pip install asciinema Install with pip
pipx install asciinema Recommended for CLI tools

Imports

asciinema
wrong:
```
import asciinema; asciinema.record()
```
correct:
```
asciinema rec my_session.cast
```
Asciinema is primarily a command-line tool. Direct programmatic import and control of recording/playback features as a Python library are not commonly documented or intended for end-users. It's mainly used by executing the `asciinema` command in the shell or via `subprocess` calls in Python.

Quickstart

Record a terminal session, save it locally, play it back in the terminal, and then upload it to asciinema.org. The `rec` command starts a new shell where your actions are recorded. To end the recording, type `exit` or press `Ctrl+D`.

asciinema rec demo.cast
# Type some commands, then press Ctrl+D or type 'exit'
echo "Hello from Asciinema!"
pwd
ls -la
exit

asciinema play demo.cast
asciinema upload demo.cast # Will prompt for confirmation to upload to asciinema.org

view raw JSON →