0
# PlexAPI
1
2
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.
3
4
## Package Information
5
6
- **Package Name**: PlexAPI
7
- **Language**: Python
8
- **Installation**: `pip install PlexAPI`
9
- **Optional Features**: `pip install PlexAPI[alert]` (for real-time alert notifications)
10
- **Requirements**: Python 3.9+
11
12
## Core Imports
13
14
```python
15
from plexapi.server import PlexServer
16
from plexapi.myplex import MyPlexAccount
17
```
18
19
For client control:
20
21
```python
22
from plexapi.client import PlexClient
23
```
24
25
For exceptions:
26
27
```python
28
from plexapi.exceptions import PlexApiException, BadRequest, NotFound, Unauthorized, TwoFactorRequired
29
```
30
31
For real-time server monitoring:
32
33
```python
34
from plexapi.alert import AlertListener
35
```
36
37
For network discovery:
38
39
```python
40
from plexapi.gdm import GDM
41
```
42
43
## Basic Usage
44
45
```python
46
from plexapi.server import PlexServer
47
from plexapi.myplex import MyPlexAccount
48
49
# Connect to a local Plex server
50
plex = PlexServer('http://localhost:32400', token='your-token')
51
52
# Connect via MyPlex account
53
account = MyPlexAccount('username', 'password')
54
plex = account.resource('My Server').connect()
55
56
# Browse your movie library
57
movies = plex.library.section('Movies')
58
movie = movies.get('The Matrix')
59
print(f"Found: {movie.title} ({movie.year})")
60
61
# Search across all libraries
62
results = plex.search('matrix')
63
for result in results:
64
print(f"{result.title} - {result.type}")
65
66
# Control a client
67
client = plex.client('Living Room TV')
68
client.playMedia(movie)
69
client.pause()
70
```
71
72
## Architecture
73
74
PlexAPI follows a hierarchical object model that mirrors Plex's structure:
75
76
- **PlexServer**: Root server object providing access to all server functionality
77
- **Library**: Container for all media sections (Movies, TV Shows, Music, Photos)
78
- **Sections**: Typed library sections with media-specific functionality
79
- **Media Objects**: Rich objects representing movies, shows, episodes, tracks, photos
80
- **Clients**: Connected Plex players with remote control capabilities
81
- **MyPlexAccount**: Plex.tv account services for cloud features and sharing
82
83
The library uses lazy loading for efficient memory usage and provides comprehensive editing capabilities through mixins for metadata management.
84
85
## Capabilities
86
87
### Server Connection & Management
88
89
Core functionality for connecting to Plex Media Servers, managing server settings, accessing server information, and performing administrative tasks.
90
91
```python { .api }
92
class PlexServer:
93
def __init__(self, baseurl=None, token=None, session=None, timeout=None): ...
94
def search(self, query, mediatype=None, limit=None, sectionId=None): ...
95
def sessions(self): ...
96
def clients(self): ...
97
def playlists(self): ...
98
def systemAccounts(self): ...
99
def systemDevices(self): ...
100
def switchUser(self, user): ...
101
def browse(self, path): ...
102
def walk(self, path): ...
103
```
104
105
[Server Connection & Management](./server-connection.md)
106
107
### Media Library & Content
108
109
Comprehensive media library access including browsing sections, searching content, managing metadata, and working with movies, TV shows, music, and photos.
110
111
```python { .api }
112
class Library:
113
def sections(self): ...
114
def section(self, name): ...
115
def sectionByID(self, id): ...
116
def search(self, title=None, libtype=None, **kwargs): ...
117
def cleanBundles(self): ...
118
def emptyTrash(self): ...
119
def optimize(self): ...
120
121
class MovieSection:
122
def all(self): ...
123
def get(self, title, year=None): ...
124
def search(self, title=None, **kwargs): ...
125
def history(self): ...
126
```
127
128
[Media Library & Content](./media-library.md)
129
130
### Client Control & Playback
131
132
Control Plex client applications, manage playback, navigate interfaces, and handle media streaming to various devices including specialized Sonos support.
133
134
```python { .api }
135
class PlexClient:
136
def connect(self, timeout=None): ...
137
def playMedia(self, media, offset=0, **params): ...
138
def play(self, mtype='music'): ...
139
def pause(self, mtype='music'): ...
140
def stop(self, mtype='music'): ...
141
```
142
143
[Client Control & Playback](./client-control.md)
144
145
### Account Management & Sharing
146
147
MyPlex account services for user authentication, server sharing, managed users, friend invitations, and cloud-based features like watchlists and content discovery.
148
149
```python { .api }
150
class MyPlexAccount:
151
def __init__(self, username=None, password=None, token=None, **kwargs): ...
152
def resources(self): ...
153
def users(self): ...
154
def createHomeUser(self, user, server, sections=None, **kwargs): ...
155
def watchlist(self, filter=None, sort=None, libtype=None, **kwargs): ...
156
```
157
158
[Account Management & Sharing](./account-management.md)
159
160
### Playlists & Collections
161
162
Create and manage playlists and collections, organize media content, and control playback queues for seamless media experiences.
163
164
```python { .api }
165
class Playlist:
166
def items(self): ...
167
def addItems(self, items): ...
168
def removeItems(self, items): ...
169
def moveItem(self, item, after): ...
170
def updateFilters(self, **kwargs): ...
171
def sync(self, client, **kwargs): ...
172
173
class Collection:
174
def items(self): ...
175
def addItems(self, items): ...
176
def removeItems(self, items): ...
177
def moveItem(self, item, after): ...
178
def updateFilters(self, **kwargs): ...
179
def mode(self, mode): ...
180
def sort(self, field, **params): ...
181
```
182
183
[Playlists & Collections](./playlists-collections.md)
184
185
### Real-time Server Monitoring
186
187
WebSocket-based real-time monitoring of server events, activities, and notifications for building responsive Plex applications.
188
189
```python { .api }
190
class AlertListener:
191
def __init__(self, server, callback, **kwargs): ...
192
def start(self): ...
193
def stop(self): ...
194
```
195
196
[Real-time Server Monitoring](./alert-system.md)
197
198
### Mobile Sync Management
199
200
Manage mobile sync items, transcoding settings, and device synchronization for offline media access.
201
202
```python { .api }
203
class SyncItem:
204
def __init__(self, server, data, initpath): ...
205
def create(self, **kwargs): ...
206
def delete(self): ...
207
208
class SyncList:
209
def __init__(self, server, items): ...
210
def sync(self, **kwargs): ...
211
```
212
213
[Mobile Sync Management](./sync-management.md)
214
215
## Types
216
217
```python { .api }
218
# Exception Classes
219
class PlexApiException(Exception): ...
220
class BadRequest(PlexApiException): ...
221
class Unauthorized(BadRequest): ...
222
class TwoFactorRequired(Unauthorized): ...
223
class NotFound(PlexApiException): ...
224
class UnknownType(PlexApiException): ...
225
class Unsupported(PlexApiException): ...
226
227
# Core Base Classes
228
class PlexObject:
229
def reload(self): ...
230
def edit(self, **kwargs): ...
231
232
class Playable:
233
def play(self, client=None): ...
234
def markPlayed(self): ...
235
def markUnplayed(self): ...
236
237
# Real-time Monitoring
238
class AlertListener:
239
def __init__(self, server, callback, **kwargs): ...
240
def start(self): ...
241
def stop(self): ...
242
243
# Network Discovery
244
class GDM:
245
def scan(self, scan_for='client', timeout=1.0): ...
246
def find_by_content_type(self, value): ...
247
248
# Mobile Sync
249
class SyncItem:
250
@property
251
def title(self): ...
252
@property
253
def status(self): ...
254
def create(self, **kwargs): ...
255
def delete(self): ...
256
257
class SyncList:
258
def sync(self, **kwargs): ...
259
def unsync(self, **kwargs): ...
260
261
# Settings Management
262
class Settings:
263
def get(self, key): ...
264
def save(self): ...
265
266
class Setting:
267
@property
268
def value(self): ...
269
def setValue(self, value): ...
270
```