Registry / communication / plexapi

plexapi

JSON →
library4.18.2pypypi✓ verified 21d ago

PlexAPI is a Python library that provides bindings for the Plex Media Server API. It allows programmatic interaction with your Plex server, enabling tasks such as managing libraries, controlling media playback, retrieving metadata, and more. The library is actively maintained, with frequent releases, typically every few weeks.

pip install plexapi
INSTALL
IMPORT
SIG · PLEXAPI
P
plexapi
communicationpythonv4.18.2
Install
2.3s avg
Import
485ms
Disk
21MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v4.18.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.103.95 runs
installs and imports cleanly · install 0.0s · import 0.500s · 22.7MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 2.3s · import 0.470s · 23MB
21MB installed
● package 21MB
Code
Verified usage

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

PlexServer
from plexapi.server import PlexServer

Connects to a Plex Media Server using provided URL and token, then lists available libraries and demonstrates how to find a specific media item.

import os from plexapi.server import PlexServer # Replace with your Plex URL and token, or set as environment variables # Example: PLEX_URL='http://your_plex_ip:32400', PLEX_TOKEN='YOUR_PLEX_TOKEN' PLEX_URL = os.environ.get('PLEX_URL', 'http://localhost:32400') # Default for local access PLEX_TOKEN = os.environ.get('PLEX_TOKEN', 'YOUR_PLEX_TOKEN') # Get from Plex settings > Network > Show Advanced > token try: plex = PlexServer(PLEX_URL, PLEX_TOKEN) print(f"Connected to Plex server: {plex.friendlyName}") # List all libraries print("\nLibraries:") for section in plex.library.sections(): print(f"- {section.title} ({section.type})") # Example: Find a movie in a 'Movies' library # Adjust 'Movies' to the actual name of your movie library try: movies_library = plex.library.section('Movies') inception_movie = movies_library.get('Inception') print(f"\nFound movie: {inception_movie.title} ({inception_movie.year})") except Exception as e: print(f"\nCould not find 'Movies' library or 'Inception': {e}") except Exception as e: print(f"Error connecting to Plex or performing operations: {e}") print("Please ensure PLEX_URL and PLEX_TOKEN are correctly configured in environment variables or directly in the script.")
Debug
Known issues
breakingPlexAPI now requires Python 3.10 or newer. Earlier Python versions are no longer supported.
fix
Upgrade your Python environment to version 3.10 or later.
affects: >=4.18.0
breakingAll previously deprecated methods have been removed.
fix
Review your code for usage of methods marked as deprecated in earlier versions. Consult the PlexAPI documentation or GitHub releases for alternative or updated methods.
affects: >=4.18.0
breakingThe `authToken` attribute has been removed from local server account objects. Direct access to this attribute is no longer available.
fix
Rely on the token provided during `PlexServer` instantiation. If interacting with local server accounts, avoid directly accessing `authToken` from the account object.
affects: >=4.18.0
breakingThe `Hub.items` property has been changed to a `Hub.items()` method.
fix
Update your code to call `Hub.items()` instead of accessing `Hub.items` as a property (e.g., `hub.items` -> `hub.items()`).
affects: >=4.17.0
gotchaAccessing `MediaPart.exists` and `MediaPart.accessible` attributes now requires explicitly reloading the `MediaPart` object with `checkFiles=True` to ensure up-to-date status.
fix
Before checking `mediaPart.exists` or `mediaPart.accessible`, call `mediaPart.reload(checkFiles=True)`.
affects: >=4.15.16
Errors
Common errors & fixes
plexapi.exceptions.Unauthorized: Invalid username/password or token.
The provided Plex Media Server URL or authentication token is incorrect, expired, or the server is not accessible due to network issues like a firewall or the server being offline.
fix
Verify that the `baseurl` (including port, typically `32400`) and the `token` are correct and current. Ensure the Plex Media Server is running and accessible from the machine running the `plexapi` script. Example: `plex = PlexServer('http://YOUR_PLEX_IP:32400', 'YOUR_PLEX_TOKEN')`
AttributeError: 'PlexServer' object has no attribute 'baseurl'
This error occurs when attempting to access an attribute or call a method that either does not exist on the `PlexServer` object, has been renamed in a different `plexapi` version, or is not a public attribute.
fix
Consult the `plexapi` documentation for the correct attribute names and methods for your installed library version. Avoid directly accessing internal attributes (often prefixed with an underscore, like `_baseurl`). If referencing older code, update to match current API usage.
TypeError: playMedia() missing 1 required positional argument: 'media'
This error indicates that the `playMedia` method was called without providing the necessary `media` object as an argument. The method expects a media item (like a Movie or Episode object), not just a key.
fix
First, retrieve the specific media item (e.g., using `plex.library.section('Movies').get('Movie Title')`) and then pass that object to the `playMedia` method. Example: `movie = plex.library.section('Movies').get('Movie Title'); client.playMedia(movie)`
No results found for {search_query}
This message appears when a search query within a Plex library section does not yield any matching results, possibly due to a typo, incorrect search parameters, or the media not being present.
fix
Double-check the spelling of the search query and the availability of the media in your Plex library. Try broadening the search (e.g., using partial titles) or searching in different library sections to confirm the item's presence. Example: `movies.search(title='Partial Title')`
Upgrade
Version history
4.18.2latest on PyPI · released Jul 10, 2026
Audit
Dependencies
requestsrequiredUsed for HTTP requests to the Plex API.
cachetoolsrequiredProvides caching utilities for API responses.
websocket-clientrequiredUsed for real-time communication with Plex clients and server.
Agent activity
12 hits · last 30 days
node
10
OpenAI (training)
1
Resources
plexapi — pip install plexapi · libregistry