🎬 Command line utility for synchronizing Plex watched / seen status
Switch branches/tags
Clone or download



A simple command-line utility to synchronize watched / seen status between different Plex Media Servers.

npm Travis Dependencies Greenkeeper badge MIT license



  • Syncs watch status between different Plex servers.


  • NodeJS 4+


plex-sync is installed via NPM:

$ npm install -g plex-sync


There are several available configuration environment variables:

Variable Description
PLEX_TOKEN The API token used to access your Plex server. To locate this token, follow the instructions here, or use this bookmarklet. The Plex token must be set on the arguments or via the environment variable.
DRY_RUN Set this environment variable to make plex-sync print out what it was planning to do rather than actually perform the synchronization.
MATCH_TYPE Can be either fuzzy (default) or precise. When the matching is fuzzy, the script will match items by their year and title. When the matching is precise, the script matches items by their internal Plex GUID, which is usually the IMDb or TMDb ID. This requires an individual API request to be performed for each item (each movie, each TV episode, etc.) and thus is very slow and can potentially overwhelm and crash the Plex server. Use at your own risk.
RATE_LIMIT Default 5. If the MATCH_TYPE is set to precise, this is the maximum number of concurrent API requests plex-sync will make to your server to fetch GUIDs. Use this to (potentially) alleviate performance issues with precise matching.

First, find the IDs for the libraries on each server you would like to sync. These IDs can be found at the end of the URL when viewing the library in your browser (like .../section/ID).

Next, use the CLI as follows:

$ plex-sync [https://][token@]IP[:PORT]/SECTION[,rw] [https://][token@]IP[:PORT]/SECTION[,rw]


Sync watched status between two servers, using the default port (32400), using library ID 1 for the first server and library 3 for the second:

$ plex-sync

Sync three servers, with different ports:

$ plex-sync

Sync with a server via HTTPS:

$ plex-sync https://server-domain/3

Dry run, to see what the script will do:

$ DRY_RUN=1 plex-sync

Precise matching (slow and may crash the Plex server):

$ MATCH_TYPE=precise plex-sync

Syncing between multiple Plex users (different access tokens):

$ plex-sync xxxxxx@ zzzzzz@

Unidirectional sync (read from one server, write to the other):

$ plex-sync,r,w

Complex use case:

$ plex-sync xxxx@,r https://yyyy@,w zzzz@,rw

For more complex strategies, like syncing between multiple different library mappings, just run the tool multiple times. If you need to run the synchronization on a schedule, use another scheduling tool like cron. These more advanced features may be added in the future, but currently plex-sync is very simple.


Contributions are welcome. Open a pull request or issue to contribute.


MIT license. See LICENSE for more information.