Installation

Prerequisites

Before installing Parakeet MLX, ensure your system meets these requirements:

System Requirements

Processor: Apple Silicon (M1, M2, M3, or later)
Operating System: macOS 13.0 or newer
RAM: 8GB minimum, 16GB recommended for larger models
Storage: At least 2GB free space for models and cache

Python Requirements

Python Version: 3.10 or higher

Check your Python version:

python3 --version

If you need to install or upgrade Python, we recommend using Homebrew:

brew install [email protected]

FFmpeg (CLI Only)

The CLI requires ffmpeg for audio format conversion. Install it with Homebrew:

brew install ffmpeg

Verify the installation:

ffmpeg -version

FFmpeg is only required for the CLI tool. If you’re using Parakeet MLX as a Python library, you can skip this step.

Installation Methods

uv (Recommended)
pip
From Source

Using uv

uv is a fast Python package installer and resolver. It’s the recommended way to install Parakeet MLX.

Install uv

If you don’t have uv installed, get it with:

curl -LsSf https://astral.sh/uv/install.sh | sh

Add to Python Project

To use Parakeet MLX in your Python project:

uv add parakeet-mlx -U

This adds parakeet-mlx to your project dependencies and installs it.

Install CLI Tool

To install the parakeet-mlx command-line tool globally:

uv tool install parakeet-mlx -U

The -U flag ensures you get the latest version.

Verify Installation

Test that the CLI is working:

parakeet-mlx --help

You should see the help message with all available options.

Using uv provides faster installation times and better dependency resolution compared to pip.

Using pip

Install Parakeet MLX using Python’s standard package manager:

Install Package

pip install parakeet-mlx -U

The -U flag upgrades to the latest version if you already have it installed.

Verify Installation

Check that both the library and CLI are available:

# Test CLI
parakeet-mlx --help

# Test Python import
python3 -c "from parakeet_mlx import from_pretrained; print('Success!')"

If you’re using a virtual environment, make sure it’s activated before installing:

source venv/bin/activate  # or your venv activation command
pip install parakeet-mlx -U

Installing from Source

For development or to use the latest unreleased features:

Clone Repository

git clone https://github.com/senstella/parakeet-mlx.git
cd parakeet-mlx

Install in Development Mode

Using pip:

pip install -e .

Or with uv:

uv pip install -e .

The -e flag installs in editable mode, so changes to the source code are immediately reflected.

Run Tests (Optional)

If you want to contribute or verify your installation:

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

Post-Installation Setup

Model Cache Directory

By default, Parakeet MLX stores downloaded models in Hugging Face’s cache directory (~/.cache/huggingface/hub). You can customize this location:

export HF_HOME="/path/to/your/cache"
# Or more specifically:
export HF_HUB_CACHE="/path/to/your/cache/hub"

Models are typically 600MB to 1.1GB in size. Ensure you have sufficient disk space in your cache directory.

Pre-downloading Models

You can download models ahead of time to avoid delays during first use:

from parakeet_mlx import from_pretrained

# Download the default model
model = from_pretrained("mlx-community/parakeet-tdt-0.6b-v3")
print("Model downloaded and ready!")

Or using the CLI:

# The model downloads automatically on first transcription
parakeet-mlx --model mlx-community/parakeet-tdt-0.6b-v3 test.mp3

Verification

Test your installation with a quick transcription:

# Create a test audio file (requires `say` command on macOS)
say "Hello, this is a test of Parakeet MLX" -o test.aiff

# Transcribe it
parakeet-mlx test.aiff

# Check the output
cat test.srt

Upgrading

To upgrade to the latest version of Parakeet MLX:

# For CLI tool
uv tool upgrade parakeet-mlx

# For project dependency
uv add parakeet-mlx -U

Check your current version:

pip show parakeet-mlx | grep Version

Uninstallation

To remove Parakeet MLX:

# Remove CLI tool
uv tool uninstall parakeet-mlx

# Remove from project
uv remove parakeet-mlx

To also remove downloaded models:

rm -rf ~/.cache/huggingface/hub/models--mlx-community--parakeet*

Troubleshooting

Command not found: parakeet-mlx

If the CLI isn’t available after installation:

Make sure your PATH includes pip’s bin directory:

echo $PATH | grep -q "$(python3 -m site --user-base)/bin" || \
  echo 'export PATH="$(python3 -m site --user-base)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Try running with Python directly:
```
python3 -m parakeet_mlx.cli --help
```

Reinstall with the --force-reinstall flag:

pip install --force-reinstall parakeet-mlx

Import Error: No module named 'mlx'

This usually means MLX isn’t compatible with your system. Parakeet MLX requires:

Apple Silicon Mac (M1 or later)
macOS 13.0 or newer

Verify your system:

# Check processor
sysctl -n machdep.cpu.brand_string

# Check macOS version
sw_vers

If you have an Intel Mac, Parakeet MLX won’t work. Consider using alternatives like OpenAI Whisper.

FFmpeg not found

If you get an error about ffmpeg when using the CLI:

# Install ffmpeg
brew install ffmpeg

# Verify it's in your PATH
which ffmpeg

If Homebrew isn’t installed:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Out of Memory Errors

If you encounter memory issues with large audio files or models:

Use chunking for long audio:

parakeet-mlx long_audio.mp3 --chunk-duration 120

Enable local attention:

parakeet-mlx long_audio.mp3 --local-attention

Use a smaller model:

parakeet-mlx audio.mp3 --model mlx-community/parakeet-ctc-0.6b

Close other applications to free up memory

Slow First Run

The first transcription will be slower because:

Model download: Models are 600MB-1.1GB and download on first use
MLX compilation: The first forward pass compiles optimized kernels

This is normal and only happens once. Subsequent transcriptions will be much faster.Monitor download progress:

parakeet-mlx audio.mp3 --verbose

Get Started

Core Concepts

Guides

Advanced

Prerequisites

Installation Methods

Using uv

Using pip

Installing from Source

Post-Installation Setup

Model Cache Directory

Pre-downloading Models

Verification

Upgrading

Uninstallation

Troubleshooting

Next Steps

Quick Start Guide

Python API Reference

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Advanced

​Prerequisites

​Installation Methods

​Using uv

​Using pip

​Installing from Source

​Post-Installation Setup

​Model Cache Directory

​Pre-downloading Models

​Verification

​Upgrading

​Uninstallation

​Troubleshooting

​Next Steps

Quick Start Guide

Python API Reference

Build docs developers (and LLMs) love

Prerequisites

Installation Methods

Using uv

Using pip

Installing from Source

Post-Installation Setup

Model Cache Directory

Pre-downloading Models

Verification

Upgrading

Uninstallation

Troubleshooting

Next Steps