pvporcupine

library4.0.2pypypi✓ verified 86d ago

Porcupine is a highly accurate and lightweight wake word (hotword / keyword) detection engine, developed by Picovoice. It enables real-time voice trigger detection in Python with support for multiple platforms and languages. The current version is 4.0.2, requiring Python >=3.9.

ai-ml llm-agents

pip install pvporcupine

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PVPORCUPINE

pvporcupine

ai-mlpythonv4.0.2

Install

1.6s avg

Import

57ms

Disk

23MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v4.0.2 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.056s · 24.8MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.6s · import 0.058s · 25MB

23MB installed

● package 23MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Porcupine

✓ from pvporcupine import Porcupine

porcupine

✓ import pvporcupine

✗ import porcupine

The top-level package is pvporcupine, not porcupine.

Initialize Porcupine with a built-in keyword. Requires a Picovoice Access Key from console.picovoice.ai.

import pvporcupine access_key = os.environ.get('PICOVOICE_ACCESS_KEY', '') # Shortcuts for built-in wake words: 'Hey Google', 'Alexa', etc. porcupine = pvporcupine.create(access_key=access_key, keywords=['picovoice']) # The object is ready to process audio frames print(f"Sample rate: {porcupine.sample_rate}") print(f"Frame length: {porcupine.frame_length}") print(f"Version: {porcupine.version}") porcupine.delete()

Debug

Known issues

breakingv4.0 removed support for custom keyword files (.ppn) via file path. You must use the new 'builtin_keywords' or 'keyword_paths' list of strings for paths.

fix

Use keyword_paths=["/path/to/keyword.ppn"] instead of a single string or path object.

affects: >=4.0.0

breakingv4.0 changed the default audio sample rate and frame length. Code relying on old constants may break.

fix

Check the actual sample_rate and frame_length from the Porcupine instance after creation.

affects: >=4.0.0

deprecatedThe 'library_path' and 'model_file_path' parameters were deprecated in v3.0 and removed in v4.0. Use 'library_path' and 'model_path' instead.

fix

Pass arguments as library_path and model_path (singular).

affects: >=3.0.0

gotchaYou must call porcupine.delete() to release resources. Failure to do so causes memory leaks and might lock audio devices.

fix

Always use a try-finally block or a context manager if available.

affects: all

gotchaThe process() method expects numpy int16 arrays. Mismatched types cause silent failures or high CPU usage.

fix

Ensure audio frames are decoded to 16-bit signed integers. For example, using struct.unpack or pvrecorder.

affects: all

Errors

Common errors & fixes

ImportError: No module named 'pvporcupine'

Package not installed or installed in a different environment (e.g., Conda).

fix

Run 'pip install pvporcupine' in the active virtual environment.

pvporcupine.PorcupineInvalidArgumentError: Invalid access key 'demo'.

Using the demo access key without purchasing or obtaining a valid key.

fix

Sign up at console.picovoice.ai and use the generated AccessKey string.

RuntimeError: Porcupine engine failed to initialise.

Missing or incompatible audio library, or the platform architecture is unsupported.

fix

Install pyaudio ('pip install pyaudio') and ensure your OS is supported (x86_64, arm64, etc.).

AttributeError: module 'pvporcupine' has no attribute 'create'

Using an old version of pvporcupine (<2.0) that used a different API.

fix

Upgrade to the latest version: 'pip install --upgrade pvporcupine'.

Upgrade

Version history

4.0.2latest on PyPI · released Feb 13, 2026

Audit

Dependencies

pyaudiooptionalRequired for audio input from microphone in demos.

Agent activity

21 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/Picovoice/porcupine ↗

packagehttps://pypi.org/project/pvporcupine/ ↗

homepagehttps://picovoice.ai ↗