parakeet-mlx runs Nvidia's ASR models on Apple Silicon through MLX

Nvidia's Parakeet models running on Apple Silicon

parakeet-mlx is a Python implementation of Nvidia's Parakeet automatic speech recognition models, written to run on Apple Silicon using MLX, the array framework for Apple hardware. The package description puts it plainly: an implementation of the Nvidia's Parakeet models for Apple Silicon using MLX.

The point of the project is portability of the model, not invention of a new one. Parakeet is Nvidia's ASR model family, and this repository provides a path to running it on a Mac, where the original stack does not go. The default model is the Hugging Face repository `mlx-community/parakeet-tdt-0.6b-v3`, a converted version of the TDT variant, and the README points at the `mlx-community/parakeet` collection on Hugging Face for the rest.

The audience is fairly specific: an engineer or researcher with a Mac who needs speech to text locally, and who does not want audio leaving the machine. The packaging confirms the intent. The project requires Python 3.10 or newer and depends on `mlx>=0.22.1`, `huggingface-hub>=0.30.2`, `librosa>=0.11.0`, `numpy>=2.2.5`, `dacite>=1.9.2` and `typer>=0.15.3`. There is no torch dependency, which is the whole point: the model runs through MLX on the local accelerator instead.

The license is Apache-2.0, and the package builds with setuptools. The console entry point is `parakeet-mlx`, mapped to `parakeet_mlx.cli:app`.

Installing with uv or pip, and the ffmpeg prerequisite

Installation is short, with one dependency that is not a Python package at all. The README puts a note before the install steps: make sure you have `ffmpeg` installed on your system first, otherwise the CLI will not work properly. That is a system-level requirement and it is the most likely first stumble, since Python installs will not supply it.

The recommended route uses uv:

uv add parakeet-mlx -U

For a standalone CLI rather than a project dependency:

uv tool install parakeet-mlx -U

And with pip:

pip install parakeet-mlx -U

The `-U` flag on each is what upgrades an existing install to the newest published version.

Worth noting what is not in the dependency list. There is no `soundfile`, no `torch`, and no separate ASR dependency, so decoding of common formats is handled through ffmpeg and the model runs on MLX. The `-U` upgrade flag also matters for the API surface, since the package version moves and the CLI options have grown over time.

One thing a reader might expect and will not find: no Docker instructions and no Linux notes. The package is for Apple Silicon, and nothing in the documentation suggests it runs anywhere else.

The CLI transcribes files and writes srt, vtt, txt or json

The command surface is `parakeet-mlx <audio_files> [OPTIONS]`, taking one or more audio files, with WAV and MP3 given as examples. The basic invocation writes transcript files next to where you run it:

# Basic transcription
parakeet-mlx audio.mp3

# Multiple files with word-level timestamps of VTT subtitle
parakeet-mlx *.mp3 --output-format vtt --highlight-words

# Generate all output formats
parakeet-mlx audio.mp3 --output-format all

Output control is the most developed part of the interface. `--output-format` selects between txt, srt, vtt, json and all, and the environment variable `PARAKEET_OUTPUT_FORMAT` sets the same thing. `--output-dir` chooses where files land, defaulting to the current directory, and `--output-template` controls the filename with `{parent}`, `{filename}`, `{index}` and `{date}` available as placeholders. The filename template can also come from `PARAKEET_OUTPUT_TEMPLATE`.

The `--highlight-words` flag enables word-level timestamps in the SRT and VTT outputs, which is what turns a plain transcript into a subtitle file that highlights the word being spoken. `--verbose` prints detailed progress information for long jobs.

One detail worth flagging for anyone writing scripts around this: every option also has an environment variable equivalent, named `PARAKEET_` plus the option name in capitals and separated by dashes. That makes it straightforward to keep a profile of settings in the environment instead of on the command line.

Chunking, local attention and beam decoding for long audio

Long audio is handled in two ways, and the two mechanisms solve different problems.

Chunking splits the audio into overlapping segments. `--chunk-duration` defaults to 120 seconds and `--overlap-duration` to 15 seconds, with `0` disabling chunking entirely. The overlap is what stops a word that straddles a boundary from being cut in half. Both are settable through the environment as `PARAKEET_CHUNK_DURATION` and `PARAKEET_OVERLAP_DURATION`.

Local attention is the alternative to chunking. The `--full-attention` and `--local-attention` flags default to full attention, and the README states the expected use case for local attention is long audio transcribed without chunking. Local attention reduces intermediate memory usage, and `--local-attention-context-size` sets the window in frames of the Parakeet model, defaulting to 256. The flag is a boolean through `PARAKEET_LOCAL_ATTENTION`.

Beam decoding is the third lever, and it is the most constrained. The default decoding method is `greedy`, with `beam` as the alternative, and the README notes that beam is only available for TDT models for now. The beam parameters are `--beam-size` at 5, `--length-penalty` at 0.013, `--patience` at 3.5 and `--duration-reward` at 0.67, the last of which shifts the balance between token log probabilities and duration log probabilities. Each of these only takes effect while beam decoding is active.

Precision is a separate switch: `--fp32` and `--bf16`, with `bf16` as the default.

The Python API returns aligned sentences and tokens

The library interface is the more precise of the two, and it starts with `from_pretrained`:

from parakeet_mlx import from_pretrained

model = from_pretrained("mlx-community/parakeet-tdt-0.6b-v3")

result = model.transcribe("audio_file.wav")

print(result.text)

The result object is structured in three levels. `AlignedResult` is the top level and holds the full `text` and a `sentences` list. Each `AlignedSentence` carries its own `text`, a `start` and `end` in seconds, the `duration` between them, and a `tokens` list of `AlignedToken` entries, each with word level text and precise start and end timestamps. Reading `result.sentences` gives you the alignment structure directly, with the documented shape shown as `AlignedSentence(text=..., start=..., end=..., duration=..., tokens=[...])`.

Both advanced CLI features have API equivalents. `transcribe` accepts `chunk_duration` and `overlap_duration` arguments, so the 120 and 15 second defaults can be overridden per call rather than globally. Beam decoding is expressed as a `DecodingConfig` holding a `Beam` object with `beam_size`, `length_penalty`, `patience` and `duration_reward`, and sentence splitting is a `SentenceConfig` with `max_words`, `silence_gap` and `max_duration`.

The `from_pretrained` call downloads from Hugging Face and stores the model in the HF cache folder, and you can redirect that with a `cache_dir` argument. The returned object is one of the Parakeet variants: `ParakeetTDT`, `ParakeetRNNT`, `ParakeetCTC` or `ParakeetTDTCTC`.

Model caching and the practical limits of the local path

There is no release infrastructure behind this package, and that shapes how you should treat it. The repository has no GitHub releases at all. The version lives in `pyproject.toml`, where it is currently 0.5.3, and the last push was on 2026-10-01. There is no changelog, no compatibility matrix and no list of supported Parakeet checkpoints.

The model download is the other constraint. `from_pretrained` fetches from Hugging Face and caches the result, and the default model is a 0.6b parameter TDT variant. The README does not document the download size or the memory the model needs, so the practical figures have to come from your own run. The `--cache-dir` option, or the `PARAKEET_CACHE_DIR` variable, exists precisely because the default location may not be what you want. Without it, the cache follows Hugging Face's default, which is `~/.cache/huggingface` or wherever `HF_HOME` or `HF_HUB_CACHE` points, effectively `$HF_HOME/hub`.

Two failure modes are visible in the documentation. The first is the missing `ffmpeg`, which breaks the CLI rather than the API path, since the API examples read local files directly. The second is version mismatch between the CLI and the model: the documentation states that beam decoding is only available for TDT models for now, so pointing `--model` at an RNNT or CTC checkpoint silently removes an option you may have configured.

A third limitation is more basic. This is a local, single machine tool. There is no batching service, no queue and no server mode in the documentation, so any workload that is meant to run on GPU hardware is out of scope by construction.

Where a hosted API or a PyTorch build fits better

The obvious alternative is to run the same Parakeet models through Nvidia's own stack, which is where they were trained and where the tooling around them lives. The difference in approach is the framework: PyTorch on CUDA versus MLX on Apple Silicon. Everything else, the model family and the general shape of the pipeline, stays the same.

The MLX path wins on a Mac for two reasons. There is no CUDA installation to manage, and inference runs on hardware already present in the machine rather than on a rented GPU. For a developer who only needs to transcribe a handful of files, that removes the whole operational layer.

The PyTorch path wins in three situations. It is the reference implementation, so it is where a checkpoint with unusual behaviour is easiest to debug. It is what a deployment on Linux GPU hardware needs. And it is not tied to a single vendor's accelerator, which matters if the model has to run in more than one place.

A third option, a hosted transcription API, sidesteps both. The trade is that audio leaves the machine, which rules it out for anything under a privacy or data residency commitment, and it costs money per call in a way a local model does not.

For transcription quality the choice is not really about frameworks. It is about which Parakeet variant you point at, and the `--model` flag plus the Hugging Face collection give you the same choice either way.

Editorial conclusion

parakeet-mlx suits an engineer who needs speech to text on a Mac without shipping audio to a hosted API, and who is comfortable with `uv` or `pip` and a Hugging Face model download on first use. It does not suit a team that needs a supported, versioned release, since the repository has no GitHub releases and the version lives only in `pyproject.toml` at 0.5.3, and it does not suit a deployment that needs to run off a Mac. Verify three things before adopting it: that `ffmpeg` is present, since the README says the CLI will not work properly without it, that the model you plan to use is a TDT variant if you intend to use beam decoding, since the README states beam is only available for TDT models for now, and that you have decided where the Hugging Face cache lives, since the model download is several hundred megabytes and the cache path is configurable through `--cache-dir`.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. README
4. senstella/parakeet-mlx on GitHub