{"id":6519,"library":"asciinema","title":"Asciinema","description":"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.","status":"active","version":"2.4.0","language":"en","source_language":"en","source_url":"https://github.com/asciinema/asciinema/tree/python","tags":["cli","terminal","recording","screencast","documentation"],"install":[{"cmd":"pip install asciinema","lang":"bash","label":"Install with pip"},{"cmd":"pipx install asciinema","lang":"bash","label":"Recommended for CLI tools"}],"dependencies":[],"imports":[{"note":"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.","wrong":"import asciinema; asciinema.record()","symbol":"asciinema","correct":"asciinema rec my_session.cast"}],"quickstart":{"code":"asciinema rec demo.cast\n# Type some commands, then press Ctrl+D or type 'exit'\necho \"Hello from Asciinema!\"\npwd\nls -la\nexit\n\nasciinema play demo.cast\nasciinema upload demo.cast # Will prompt for confirmation to upload to asciinema.org","lang":"bash","description":"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`."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"3.x (Rust rewrite) vs 2.x (Python)"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions of the Python package (2.x)"},{"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.","message":"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.","severity":"deprecated","affected_versions":"2.x"},{"fix":"Move your existing configuration file from `$HOME/.asciinema` to `$HOME/.config/asciinema/config`.","message":"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.","severity":"gotcha","affected_versions":"< 1.1"},{"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'.","message":"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.","severity":"gotcha","affected_versions":"< 2.0"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[{"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.","cause":"The asciinema command is not installed or not in the system's PATH.","error":"asciinema: command not found"},{"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.","cause":"The user does not have the necessary permissions to execute the asciinema command or write to the specified file location.","error":"Permission denied"},{"fix":"Review the asciinema command usage by running 'asciinema --help' to see the list of supported commands and options.","cause":"An invalid or unsupported argument was passed to the asciinema command.","error":"asciinema: error: unrecognized arguments"},{"fix":"Check your internet connection and ensure you are authenticated by running 'asciinema auth'.","cause":"The upload process to asciinema.org failed, possibly due to network issues or authentication problems.","error":"asciinema: failed to upload recording"},{"fix":"Ensure your terminal supports asciinema and that there are no conflicting processes. Try recording again or consult the asciinema documentation for troubleshooting tips.","cause":"An error occurred during the recording process, potentially due to terminal incompatibility or other system issues.","error":"asciinema: failed to record session"}]}