# asciinema: recording and live streaming terminal sessions in the asciicast format

> The asciinema CLI captures a terminal session as a lightweight .cast file or streams it live, rather than encoding a screen into video. It is a good fit for sharing CLI workflows and CI-friendly capture, but it is not a screen recorder and does not run on Windows.

**asciinema/asciinema** — Terminal session recorder, streamer and player 📹

- Repository: https://github.com/asciinema/asciinema
- Website: https://asciinema.org
- Stars: 17,850 · Forks: 1,043
- Language: Rust
- License: GPL-3.0
- Published: 2026-09-21 · Updated: 2026-09-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/asciinema-asciinema

## What asciinema records that a screen recorder cannot

A screen recorder captures pixels. asciinema captures the terminal session itself, writing it to a .cast file in the asciicast format, or streaming it live to viewers. The README draws the contrast directly: typical screen recording software produces heavyweight video files such as .mp4 or .mov, while the asciinema CLI runs inside a terminal and produces lightweight recording files.

The practical difference is what you can do with the artifact afterwards. A .cast recording can be replayed inside a terminal, embedded on a web page with the asciinema player, or published to an asciinema server such as asciinema.org. The README also notes native reading and writing of zstd-compressed recordings, which it says come out at 8% of the original size on average. That number is the project's own claim, not an independent measurement.

The intended audience is people who need to show a command-line procedure: documentation writers, maintainers writing reproduction steps, support engineers, and anyone recording a CI job. If the thing you need to show is a GUI application, this is the wrong tool, because there is no terminal session to capture.

## The mechanism: a terminal-side recorder with a built-in HTTP server

The shape of the tool is visible in its dependencies. The Cargo.toml lists nix with the fs, term, process, signal and poll features, which is the layer that talks to the terminal, plus avt, a terminal emulator library. The recording side is therefore not reading a framebuffer; it is sitting between your shell and the terminal. The README describes capture of terminal session output, optional keyboard input capture, and configurable environment variable capture, along with session metadata such as terminal size, terminal theme, command and title.

Streaming is a separate path with its own stack. The dependencies include axum with http1 and ws, tokio, tokio-tungstenite, tower-http and rust-embed. That matches the README's description of local and remote live streaming, including a built-in HTTP server with an embedded web player for LAN or localhost viewing. Remote streaming goes through a relay, which the README identifies as an asciinema server.

Reading and conversion also live in the same binary. The README lists conversion from asciicast v1, v2 and v3 to asciicast v2 or v3, raw terminal output, or plain text, plus concatenation of multiple recordings with timing adjusted automatically. Playback from local files, stdin or HTTP(S) URLs is listed as supported. One dependency worth noting for anyone auditing the network path: reqwest is configured with rustls-tls-native-roots rather than a bundled OpenSSL, and tokio-tungstenite uses the same native-roots trust setup.

## Installing asciinema and recording a first session

The README points to the Getting started guide for a full installation and usage overview, and the Building section gives the from-source route. The one-step build downloads the source, compiles it and installs the binary into $HOME/.cargo/bin:

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

This requires the Rust toolchain with Cargo. The README states Rust 1.82 or later, and Cargo.toml sets rust-version = "1.82.0", so those agree. After the install finishes, make sure $HOME/.cargo/bin is in your $PATH, or the shell will not find the command.

If you prefer a local checkout, the README gives this sequence. The Nix dev shell is described as the recommended way to get the toolchain:

```bash
git clone https://github.com/asciinema/asciinema
cd asciinema
nix develop
cargo build --release
```

The build writes the binary to target/release/asciinema, which you can copy into a directory on your $PATH. To also generate man pages and shell completion files, set ASCIINEMA_GEN_DIR to the destination before building:

```bash
ASCIINEMA_GEN_DIR=/foo cargo build --release
```

With that, the man pages land in /foo/man/ and the completion files in /foo/completion/. There is also a Dockerfile in the repository that builds the binary in a rust:1.90.0-slim-trixie stage and copies it into a debian:trixie-slim runtime image, with the binary as the entrypoint.

The first real use is one command. The README shows it:

```bash
asciinema rec demo.cast
```

Run it in your shell and the session is recorded to demo.cast. The README does not spell out the exit gesture or the exact key sequence in the text available here; the quick-start guide linked from the README is where recording controls and keyboard bindings are documented. To stream instead of record, the README gives two forms:

```bash
asciinema stream -l
asciinema stream -r
```

The -l form starts the built-in HTTP server for LAN or localhost viewing. The -r form streams through a relay, meaning an asciinema server. Both flags appear in the README exactly as written here.

## Where asciinema does not fit

The clearest boundary is platform support. The README states that asciinema runs on GNU/Linux, macOS and FreeBSD, and adds a note that Windows is currently not supported, linking to a discussion and suggesting PowerSession as an alternative. If your team is on Windows, this is not a tool you can standardise on, and the project says so rather than leaving it to be discovered.

A second boundary is the nature of the artifact. A .cast file is not a video. The README lists conversion to raw terminal output and plain text, but converting to GIF or MP4 is not among the documented features here. The related searches around asciinema to gif, to video and to mp4 are a real signal that people expect video output, and the answer from this material is that the CLI itself does not advertise those conversions. You would be looking at a separate tool.

A third consideration is that recording captures what happens in the terminal, including anything you type and, optionally, environment variables. The README lists keyboard input capture and configurable environment variable capture as features, which means the recording can contain secrets typed at a prompt or exported in the environment. The README does not document a redaction step for recordings. Treat the .cast file with the same care as a shell transcript, and check the configuration options for capture before recording anything sensitive.

Finally, the project is donation and sponsorship funded, and the README mentions consulting services for integration or customisation. That is a maintenance model worth knowing about if you plan to depend on it heavily. The last push to the repository was on 2026-08-14, and the most recent release listed is v3.2.1 from 2026-06-16.

## asciinema versus script and ttyrec

The closest comparison in the search data is asciinema vs script, the util-linux command that writes a terminal session to a typescript file. Both sit in the terminal and both produce a file, but the output is not equivalent. script writes a raw transcript; asciinema writes asciicast, a format with timing information that the asciinema player and asciinema server understand. That is why an asciinema recording can be replayed at adjustable speed with idle time limiting, or embedded on a page, while a typescript file is replayed by cat and loses timing.

asciinema also does more than capture. The README lists live streaming to local and remote viewers, combined sessions that record to a file while streaming locally and remotely at once, concatenation of multiple recordings with timing adjusted automatically, and conversion between asciicast versions. script does none of that.

The trade-off runs the other way too. script is part of util-linux on essentially every Linux system, so there is nothing to install. asciinema is a Rust binary you build or install, with a minimum toolchain of 1.82. If all you need is a log of what a script printed, script is the smaller answer. If you need a replayable, shareable, streamable artifact, that is the case asciinema is built for.

ttyrec is the other comparison people search for. The README does not mention ttyrec, so the honest position is that this material does not document a relationship between them beyond both being terminal session recorders.

## Licence and upgrade cost

The repository is licensed GPL-3.0-or-later. Cargo.toml declares license = "GPL-3.0-or-later", the README says all code is licensed under the GPL, v3 or later, and the copyright line reads © 2011 Marcin Kulik. For anyone embedding asciinema in a product or shipping a modified binary, that is a copyleft licence and the obligations differ from a permissive one. This is a description of what the repository states, not legal advice; if the licence terms matter to your distribution, have someone qualified read them.

Upgrade cost is mostly the toolchain floor. Cargo.toml sets rust-version = "1.82.0" and the README repeats 1.82 or later, so a machine with an older Rust will fail to build until the toolchain is updated. The Dockerfile uses a newer builder image, rust:1.90.0-slim-trixie, which suggests the container path is the easier one to keep current if you do not want to manage Rust on the host.

There is no documented migration burden between the 3.x releases in this material. The README does note that the current generation is 3.x on the develop branch, and that the previous 2.x generation written in Python lives on the python branch. If you are coming from 2.x, that is a rewrite in a different language rather than an in-place upgrade, and the asciicast conversion features exist partly to move older recordings forward.

## Conclusion

Adopt asciinema if you want terminal sessions captured as small .cast files that replay in a terminal, embed in a page, or stream over a built-in HTTP server, and if your machines run GNU/Linux, macOS or FreeBSD. Do not adopt it as a screen recorder, and do not expect it on Windows: the README states Windows is not supported and points to PowerSession instead. Before committing, verify on your own machine that the Rust toolchain is 1.82 or later, that $HOME/.cargo/bin is on your $PATH after cargo install, and that your target environment is one of the three supported platforms.

## FAQ

### How does asciinema work?

It runs inside a terminal and captures the session output into a lightweight .cast file in the asciicast format, or streams it live to viewers. The README contrasts this with screen recording software that produces video files such as .mp4 or .mov.

### How do I install asciinema?

The README gives a one-step source build with cargo install --locked --git https://github.com/asciinema/asciinema, which requires the Rust toolchain 1.82 or later and installs the binary into $HOME/.cargo/bin. It also points to the Getting started guide for a full installation overview.

### How to record a terminal session in Linux?

The README shows the command asciinema rec demo.cast, run in your shell, which records the session to demo.cast. asciinema runs on GNU/Linux, macOS and FreeBSD.

### How can I record a terminal session on macOS?

macOS is one of the platforms the README lists as supported, so the same asciinema rec demo.cast command applies. The toolchain requirement is Rust 1.82 or later with Cargo when building from source.

### what is asciinema

The README describes it as a command-line tool for recording and live streaming terminal sessions, writing asciicast .cast files rather than video. Recordings can be replayed in a terminal, embedded with the asciinema player, or published to an asciinema server such as asciinema.org.

### how to use asciinema

The README shows asciinema rec demo.cast to record a session to a file, and asciinema stream -l or asciinema stream -r to stream it locally or through a relay. The linked Getting started guide covers the full usage overview.

## Sources

- [asciinema/asciinema on GitHub](https://github.com/asciinema/asciinema)
- [License: GPL-3.0](https://github.com/asciinema/asciinema/blob/develop/LICENSE)
- [Project website](https://asciinema.org)
- [README](https://github.com/asciinema/asciinema/blob/develop/README.md)
- [Releases](https://github.com/asciinema/asciinema/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/asciinema-asciinema