Library / SDK
home-assistant-libs/pychromecast avatar
home-assistant-libs/pychromecast

PyChromecast: a Python library for talking to Cast devices on your LAN

Library for Python 3 to communicate with the Google Chromecast.

2,710 stars394 forksPythonMIT

At a glance

What is it?
PyChromecast is a Python 3.11+ library that discovers Chromecast and Cast-enabled devices over mDNS and drives them through the Cast protocol. It is a building block for Home Assistant integrations and custom scripts, not a consumer app.
Who is it for?
Adopt PyChromecast if you are writing Python that needs to find Cast devices on a local network and control playback, especially if you are extending Home Assistant or building a custom controller.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository received new commits within the last day.
What is it written in?
Mainly Python, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 21, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • home-assistant-libs/pychromecast2,710 ★ · +25
Star history
Repository2026-10-042026-11-21
home-assistant-libs/pychromecast2.7k2.7k

25 Stars in the last 48 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

What PyChromecast solves, and who it is for

A Chromecast is not a normal network appliance. It advertises itself over mDNS, opens a TLS socket on port 8009, and then speaks a protobuf-framed, JSON-payload protocol with namespaces such as urn:x-cast:com.google.cast.media. Writing that handshake from scratch means implementing discovery, connection setup, heartbeat, and per-namespace message routing before you can press play on anything. PyChromecast packages that work as a Python 3.11+ library, with the README describing support for auto discovery, the default media receiver, playback control, Cast API v2, channel communication with apps, and multi-room audio setups.

The intended audience is developers. The README points at Home Assistant as a ready-made solution built on the library, which tells you the primary consumer is an integration layer rather than an end user. If you are writing a script that plays a file on the kitchen speaker when a build finishes, or you are adding a new Cast app to an existing home automation stack, this is the layer that saves you from reimplementing the protocol. If you want a phone app to cast video, this is the wrong repository entirely.

How discovery, connection and controllers fit together

The data flow has three stages. First, zeroconf browses for _googlecast._tcp.local. and produces ServiceInfo records. PyChromecast wraps those into a CastInfo object, which the README shows carrying uuid, model_name, friendly_name, host, port 8009, cast_type and manufacturer. Second, a CastBrowser holds the discovered set and a listener is notified as devices appear; the README's example prints browser.devices[uuid].friendly_name from a SimpleCastListener. Third, get_listed_chromecasts returns connected device objects, and cast.wait() starts the worker thread and blocks until the device is ready.

From there, everything is a controller. The base class in pychromecast/controllers takes a namespace string, and incoming messages for that namespace are routed to receive_message. The README's minimal example returns True to signal that the message was handled, and sends outgoing messages with self.send_message. The MediaController is the fully implemented reference, and the repository also ships controllers for other apps. This is the design decision worth noting: the library does not try to model every Cast app. It gives you the transport and the routing, and expects you to encode the app-specific JSON yourself. That keeps the core small, but it also means a new app is your problem, not the maintainers'.

Installing PyChromecast and playing your first file

The package is published as PyChromecast and requires Python 3.11.0 or newer. The pyproject.toml lists protobuf, zeroconf and casttube as runtime dependencies, and requirements.txt pins them, so a plain pip install resolves the chain for you.

bash
pip install pychromecast

Discovery is the first real step. The README's pattern creates a zeroconf browser, starts discovery, and then stops it when you are done. Note that the README itself calls pychromecast.discovery.stop_discovery(browser) to shut discovery down; the top-level pychromecast module also re-exports the discovery helpers used in the examples.

python
import pychromecast
import zeroconf

zconf = zeroconf.Zeroconf()
browser = pychromecast.CastBrowser(
    pychromecast.SimpleCastListener(
        lambda uuid, service: print(browser.devices[uuid].friendly_name)
    ),
    zconf,
)
browser.start_discovery()
pychromecast.discovery.stop_discovery(browser)

For a script you usually want a named device rather than a callback. get_listed_chromecasts takes a friendly_names list and returns connected casts plus the browser. The README warns that discovery can return fewer devices than expected, and documents a discovery_timeout parameter you can raise, with 30 seconds shown as the example value.

python
chromecasts, browser = pychromecast.get_listed_chromecasts(
    friendly_names=["Living Room"], discovery_timeout=30
)
cast = chromecasts[0]
cast.wait()
print(cast.cast_info)

After wait() returns, the device is ready and cast.status shows the active app. To play something, take the media controller, hand it a URL and a MIME type, then block until the receiver is active. The README uses a public sample MP4 for this.

python
mc = cast.media_controller
mc.play_media(
    "http://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4",
    "video/mp4",
)
mc.block_until_active()
print(mc.status)
mc.pause()
mc.play()
pychromecast.discovery.stop_discovery(browser)

One practical detail from the README: the Chromecast reports whether it is the active input on the connected display, exposed as cast.status.is_active_input. The README section on ignoring CEC data is truncated in the published text, so if you are automating a TV and the input switching interferes, that property is where to look, but the full guidance is not in the README excerpt.

Where PyChromecast breaks down

The dependency on zeroconf means discovery is mDNS, and mDNS is link-local. If your Cast devices sit on a separate VLAN, or your router does not forward multicast between the client and the devices, get_listed_chromecasts returns an empty list and no amount of raising discovery_timeout fixes it. The README acknowledges slow discovery but does not document a fallback that skips mDNS and connects to a known host and port, so a routed setup is on you.

The protocol layer is also incomplete by design. The README lists the supported surface and then explains that unsupported namespaces are added through custom controllers. That is honest, but it means a proprietary Cast app that does not use the default media receiver will not work out of the box. The README's suggested workflow for that case is to capture a Chrome net-export log, filter it to SOCKET events in the netlog viewer, and reverse the JSON into a controller. That is a real reverse-engineering task, not a configuration change.

Finally, the library is a client. It has no server, no web UI, and no scheduling. Anything stateful, such as remembering which speaker was playing what, has to live in your application. If you expected a daemon you install and point a browser at, you will be disappointed.

PyChromecast compared with casting from a browser or a vendor app

The obvious alternative is not another Python library but the Google Cast button in a web page or the vendor mobile app. The difference is where the logic lives. With the Cast button, the browser negotiates with the receiver and your code only supplies a media URL and metadata through the Cast SDK in JavaScript. With PyChromecast, the negotiation happens in Python on a machine on the same network, and you own the session: you decide when to connect, which controller to attach, and how to react to status changes. That makes PyChromecast the right choice when the trigger is not a human clicking a button, for example a home automation rule or a build pipeline.

The trade-off is that the browser path gets automatic handling of things a library user must wire up, and it works from any device that can load the page. PyChromecast needs a persistent process with network access to the devices, plus a Python runtime of 3.11 or newer. If you are building an interactive web player, the Cast SDK is the shorter path. If you are building automation, PyChromecast is the layer Home Assistant itself chose, which is a strong signal about which side of that line it belongs on.

Maintenance, licensing and what an upgrade costs you

The repository is not archived, and the last push was on 2026-09-21. Releases are versioned and the current one is 14.0.10, published on 2026-03-07, with 14.0.9 and 14.0.7 before it. The cadence is irregular: roughly a year between 14.0.7 and 14.0.9, then about seven months to 14.0.10, with commits continuing after the last release. For a library this size, that pattern suggests maintenance rather than active feature development, and you should plan to read the release notes rather than assume API stability across major versions.

The licence is MIT, declared both in the repository LICENSE file and in the pyproject.toml license field. That permits commercial and closed-source use with attribution and without copyleft obligations. It does not cover the Cast protocol itself or the devices, and it says nothing about the terms you agree to when you use Google's receivers. That is a question for your own legal review, not something the repository answers.

Upgrade cost is mostly dependency churn. requirements.txt pins protobuf, zeroconf and casttube to exact versions, while pyproject.toml uses lower bounds, so a fresh pip install and a pinned environment can resolve differently. The build backend is constrained to setuptools below 85.0. If you vendor the library into a larger application, pin the same versions the project pins, and re-run your discovery and playback paths after any zeroconf bump, since that is the dependency most likely to change behaviour on unusual networks.

Editorial conclusion

Adopt PyChromecast if you are writing Python that needs to find Cast devices on a local network and control playback, especially if you are extending Home Assistant or building a custom controller. Do not adopt it if you want a graphical app, if your devices sit on a different VLAN without mDNS reflection, or if you need a supported consumer product, since the README does not document rollback, and the search results about Chromecast discontinuation refer to the hardware line, not to this library. Verify first that your Python is 3.11 or newer, that zeroconf can see the target devices, and that the namespace you need is either already implemented in pychromecast/controllers or something you are prepared to write yourself.

Frequently asked questions

Is Chromecast being discontinued?

That question is about Google's Chromecast hardware line, not about PyChromecast, and the repository material says nothing about device discontinuation. PyChromecast is a Python library for communicating with Cast devices, and its own status is separate: it is not archived, and the last push was on 2026-09-21.

Does Chromecast still work in 2026?

The repository does not address whether Google's Chromecast hardware still works, and nothing in it comments on device support timelines. What it does show is that PyChromecast, the Python client for Cast devices, had its last push on 2026-09-21 and its latest release 14.0.10 on 2026-03-07.

Why can't I cast to Chromecast anymore?

The repository material does not cover troubleshooting casting failures on the device side. The one discovery problem it does document is the opposite case: get_listed_chromecasts can find fewer devices than expected, and the README suggests raising the discovery_timeout parameter, showing 30 seconds as an example.

What device is replacing Chromecast?

This is a question about Google's hardware lineup, and the PyChromecast repository contains no information about replacement devices. The library targets Cast-enabled devices generally, and the README's example CastInfo shows a Chromecast Audio reporting model_name 'Chromecast Audio' and cast_type 'audio'.

Official sources

  1. home-assistant-libs/pychromecast on GitHub
  2. Issues
  3. License: MIT
  4. README
  5. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/home-assistant-libs-pychromecast.svg)](https://hysenlabs.com/projects/home-assistant-libs-pychromecast)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/home-assistant-libs-pychromecast.svg)](https://hysenlabs.com/projects/home-assistant-libs-pychromecast)

Was this useful?