or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

account-management.mdalert-system.mdclient-control.mdindex.mdmedia-library.mdplaylists-collections.mdserver-connection.mdsync-management.md
tile.json

tessl/pypi-plex-api

Python bindings for the Plex Media Server API, enabling programmatic interaction with Plex servers and media libraries.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/plexapi@4.17.x

To install, run

npx @tessl/cli install tessl/pypi-plex-api@4.17.0

index.mddocs/

PlexAPI

A comprehensive Python library for interacting with Plex Media Server and MyPlex (Plex.tv) services. PlexAPI provides complete programmatic access to Plex servers, enabling developers to browse media libraries, control playback on clients, manage user accounts, and access all Plex functionality available through the official web interface.

Package Information

  • Package Name: PlexAPI
  • Language: Python
  • Installation: pip install PlexAPI
  • Optional Features: pip install PlexAPI[alert] (for real-time alert notifications)
  • Requirements: Python 3.9+

Core Imports

from plexapi.server import PlexServer
from plexapi.myplex import MyPlexAccount

For client control:

from plexapi.client import PlexClient

For exceptions:

from plexapi.exceptions import PlexApiException, BadRequest, NotFound, Unauthorized, TwoFactorRequired

For real-time server monitoring:

from plexapi.alert import AlertListener

For network discovery:

from plexapi.gdm import GDM

Basic Usage

from plexapi.server import PlexServer
from plexapi.myplex import MyPlexAccount

# Connect to a local Plex server
plex = PlexServer('http://localhost:32400', token='your-token')

# Connect via MyPlex account
account = MyPlexAccount('username', 'password')
plex = account.resource('My Server').connect()

# Browse your movie library
movies = plex.library.section('Movies')
movie = movies.get('The Matrix')
print(f"Found: {movie.title} ({movie.year})")

# Search across all libraries
results = plex.search('matrix')
for result in results:
    print(f"{result.title} - {result.type}")

# Control a client
client = plex.client('Living Room TV')
client.playMedia(movie)
client.pause()

Architecture

PlexAPI follows a hierarchical object model that mirrors Plex's structure:

  • PlexServer: Root server object providing access to all server functionality
  • Library: Container for all media sections (Movies, TV Shows, Music, Photos)
  • Sections: Typed library sections with media-specific functionality
  • Media Objects: Rich objects representing movies, shows, episodes, tracks, photos
  • Clients: Connected Plex players with remote control capabilities
  • MyPlexAccount: Plex.tv account services for cloud features and sharing

The library uses lazy loading for efficient memory usage and provides comprehensive editing capabilities through mixins for metadata management.

Capabilities

Server Connection & Management

Core functionality for connecting to Plex Media Servers, managing server settings, accessing server information, and performing administrative tasks.

class PlexServer:
    def __init__(self, baseurl=None, token=None, session=None, timeout=None): ...
    def search(self, query, mediatype=None, limit=None, sectionId=None): ...
    def sessions(self): ...
    def clients(self): ...
    def playlists(self): ...
    def systemAccounts(self): ...
    def systemDevices(self): ...
    def switchUser(self, user): ...
    def browse(self, path): ...
    def walk(self, path): ...

Server Connection & Management

Media Library & Content

Comprehensive media library access including browsing sections, searching content, managing metadata, and working with movies, TV shows, music, and photos.

class Library:
    def sections(self): ...
    def section(self, name): ...
    def sectionByID(self, id): ...
    def search(self, title=None, libtype=None, **kwargs): ...
    def cleanBundles(self): ...
    def emptyTrash(self): ...
    def optimize(self): ...

class MovieSection:
    def all(self): ...
    def get(self, title, year=None): ...
    def search(self, title=None, **kwargs): ...
    def history(self): ...

Media Library & Content

Client Control & Playback

Control Plex client applications, manage playback, navigate interfaces, and handle media streaming to various devices including specialized Sonos support.

class PlexClient:
    def connect(self, timeout=None): ...
    def playMedia(self, media, offset=0, **params): ...
    def play(self, mtype='music'): ...
    def pause(self, mtype='music'): ...
    def stop(self, mtype='music'): ...

Client Control & Playback

Account Management & Sharing

MyPlex account services for user authentication, server sharing, managed users, friend invitations, and cloud-based features like watchlists and content discovery.

class MyPlexAccount:
    def __init__(self, username=None, password=None, token=None, **kwargs): ...
    def resources(self): ...
    def users(self): ...
    def createHomeUser(self, user, server, sections=None, **kwargs): ...
    def watchlist(self, filter=None, sort=None, libtype=None, **kwargs): ...

Account Management & Sharing

Playlists & Collections

Create and manage playlists and collections, organize media content, and control playback queues for seamless media experiences.

class Playlist:
    def items(self): ...
    def addItems(self, items): ...
    def removeItems(self, items): ...
    def moveItem(self, item, after): ...
    def updateFilters(self, **kwargs): ...
    def sync(self, client, **kwargs): ...

class Collection:
    def items(self): ...
    def addItems(self, items): ...
    def removeItems(self, items): ...
    def moveItem(self, item, after): ...
    def updateFilters(self, **kwargs): ...
    def mode(self, mode): ...
    def sort(self, field, **params): ...

Playlists & Collections

Real-time Server Monitoring

WebSocket-based real-time monitoring of server events, activities, and notifications for building responsive Plex applications.

class AlertListener:
    def __init__(self, server, callback, **kwargs): ...
    def start(self): ...
    def stop(self): ...

Real-time Server Monitoring

Mobile Sync Management

Manage mobile sync items, transcoding settings, and device synchronization for offline media access.

class SyncItem:
    def __init__(self, server, data, initpath): ...
    def create(self, **kwargs): ...
    def delete(self): ...

class SyncList:
    def __init__(self, server, items): ...
    def sync(self, **kwargs): ...

Mobile Sync Management

Types

# Exception Classes
class PlexApiException(Exception): ...
class BadRequest(PlexApiException): ...
class Unauthorized(BadRequest): ...
class TwoFactorRequired(Unauthorized): ...
class NotFound(PlexApiException): ...
class UnknownType(PlexApiException): ...
class Unsupported(PlexApiException): ...

# Core Base Classes  
class PlexObject:
    def reload(self): ...
    def edit(self, **kwargs): ...

class Playable:
    def play(self, client=None): ...
    def markPlayed(self): ...
    def markUnplayed(self): ...

# Real-time Monitoring
class AlertListener:
    def __init__(self, server, callback, **kwargs): ...
    def start(self): ...
    def stop(self): ...

# Network Discovery
class GDM:
    def scan(self, scan_for='client', timeout=1.0): ...
    def find_by_content_type(self, value): ...

# Mobile Sync
class SyncItem:
    @property
    def title(self): ...
    @property
    def status(self): ...
    def create(self, **kwargs): ...
    def delete(self): ...

class SyncList:
    def sync(self, **kwargs): ...
    def unsync(self, **kwargs): ...

# Settings Management
class Settings:
    def get(self, key): ...
    def save(self): ...

class Setting:
    @property
    def value(self): ...
    def setValue(self, value): ...