Refresh Metadata by Folder?

Plex Media Server Metadata & Adding Files
1

Server Version#: 1.42.1.10060
Player Version#: 4.147.1
<If providing server logs please do NOT turn on verbose logging, only debug logging should be enabled>

Firefox on Linux, Plex webpage, I found refresh metadata option under three dots at library level (left sidebar), or I can drill down and find refresh metadata option under three dots on individual media. But I can’t seem to find any option at a folder level? If none is available, is there a command line method I could script, to recurse a folder?

Kind regards.

2

Although what you ask appears to be deprecated, it’s worth a try.
In every PMS install, one of the additional helper apps is named
Plex Media Scanner and you should be able to find it in the same directory
as the Plex Media Server application. The scanner often requires an
environment variable set to find its way. On QNAP which is a Linux variant I have my environment set with an alias and the variable like this:

export PLEX_MEDIA_SERVER_APPLICATION_SUPPORT_DIR=/share/CACHEDEV1_DATA/.qpkg/PlexMediaServer/Library

alias pscan='"/share/CACHEDEV1_DATA/.qpkg/PlexMediaServer/Plex Media Scanner"'

So at a command line I can just type pscan and get the help output.
In the help output I can see there’s an action called
-r, --refresh Refresh the metadata. Deprecated.
and a directory location option. So I’m guessing this might work:

pscan -r -d /some/path/to/a/subset/of/movies

Hoping it works but I wouldn’t know if it needs a trailing slash or whatnot. Also if you get a catastrophic error just typing pscan check your alias quoting and that your ENV variable got exported correctly.

Let us know how it goes :slight_smile:

1 Like
3

Thank you! Everything’s refreshed as of now. When I can get some time I’ll set up a test and give it a shot. I appreciate the detailed info on what to look at, I’ll try and get back as soon as I can.

1 Like
4

Sorry it took me a little time to return to this. The command does not execute, it just issues a message that the command is deprecated and will be removed in a future version. Oh well. Thanks for trying to help!

5

I was able to get the command to refresh the metadata on a small library of mine in spite of the deprecated message. Let’s take a look at how it worked.

pscan -v -r -p -x -c 16

arguments

  • -v : verbose output (not sure if this does anything)
  • -r : refresh metadata action
  • -p : show progress output (never seems to do anything)
  • -x : force the refresh (refresh all items, not just ones that have changed recently)
  • -c : apply this action to a library section ID
  • 16 : the section ID of a small test library I have (I saw in the XML that key="16")

output

[~] # 
[~] # pscan -v -r -p -x -c 16
The '--refresh' operation is deprecated and will be removed in future versions of Plex Media Server.
[~] # echo $?
0
[~] #

The echo output shows the command succeeded with return code 0, meaning success, but it wasn’t clear whether success was the deprecated message or whether success meant the command actually did something. So I checked my

logs

[~] # cd "/share/CACHEDEV1_DATA/.qpkg/PlexMediaServer/Library/Plex Media Server/Logs"
[/share/.../Logs] # cat "Plex Media Scanner.log" | head
Sep 24, 2025 20:41:38.637 [139685032954624] INFO - Plex Media Scanner v1.42.2.10156-f737b826c - unknown PC unknown - build: linux-x86_64 - GMT -07:00
Sep 24, 2025 20:41:38.637 [139685032954624] INFO - Linux version: 4.14.24-qnap (#1 SMP Tue Nov 19 12:11:23 CST 2024), language: en-US
Sep 24, 2025 20:41:38.649 [139685032954624] INFO - Processor: 4-core Intel(R) Celeron(R) CPU  J1900  @ 1.99GHz
Sep 24, 2025 20:41:38.649 [139685032954624] INFO - /share/CACHEDEV1_DATA/.qpkg/PlexMediaServer/Plex Media Scanner -v -r -p -x -c 16
Sep 24, 2025 20:41:38.641 [139685033479936] DEBUG - Opening 20 database sessions to library (com.plexapp.plugins.library), SQLite 3.39.4, threadsafe=1
Sep 24, 2025 20:41:38.877 [139685033479936] DEBUG - Refreshing section 16 of type: 1
Sep 24, 2025 20:41:38.879 [139685005789952] DEBUG - Refreshing 18 IDs.
Sep 24, 2025 20:41:38.879 [139685005789952] DEBUG - Refreshing metadata for '5 Track Saw Accessories Every Woodworker Needs [agVrU-g4yTw]' (agent: tv.plex.agents.none)
Sep 24, 2025 20:41:38.880 [139685005789952] DEBUG - Refreshing metadata for 'Best Cordless Tracksaw [3I6PldFPpj0]' (agent: tv.plex.agents.none)
Sep 24, 2025 20:41:38.880 [139685005265664] DEBUG - [HCl#1] HTTP requesting GET http://127.0.0.1:32400/:/metadata/notify/changeItemState?librarySectionID=16&metadataItemID=34966&metadataType=1&state=3&parentID=-1&rootID=-1&metadataState=queued
[/share/.../Logs] #

In the above I changed to the Logs directory and did a cat of the scanner log to verify that it did the refresh, snipping the output to the first 10 lines or so.

I haven’t tried forcing a refresh on a folder yet, I’ll leave you the treasure hunt :slight_smile:
Because each Plex Media Scanner is somewhat unique to the OS it’s running on, I don’t know whether my success applies to your setup exactly.

fwiw, if you can live with refreshing a whole library, the Plex API also has an easy way to do that from a command line

caveats
One pscan command I issued against a folder did not complete and became a stuck process. It never returned to a command prompt. The usual ^c didn’t interrupt it. I had to open another ssh session to my server and use ps | grep anner to find the PID and then use kill -6 {PID}

All righty then :+1:

6

Thank you so much for all your efforts on this. As soon as I can set up another test case I will try it. Please allow me time as before to get back to you.

I do have scheduled jobs that refresh metadata for the library, they run infrequently as our library doesn’t change much, it’s mostly very old and mostly rare media that we enjoy watching from time to time. For refreshing the entire library, I usually just login to Plex web and in a couple of clicks can start the refresh. Or just trigger the scheduled job.

I have only one library, and it is large at least by my very old and slow computer’s standards as a metadata refresh on the entire library takes anywhere from 20-30 minutes to an hour or more. Did I mention it’s a very old and slow computer…

My sole reason for wanting to refresh metadata on an individual folder basis is to pick up .SRT files I just placed there. When we decide to watch something that doesn’t have subtitles, I’ll get on the ‘net right then to see if anyone has made any, sometimes I find them. We don’t want to delay watching to wait for a library refresh, so I have been logging into Plex web before every media to initiate a refresh on just that media. Tedious but not impossible. Hence my idea about a folder level refresh.

As far as I know, metadata refresh is the only thing that picks up .SRT files… Is there another way to quickly associate an .SRT file with its media? That could be done at folder level, or drag/drop multiple filenames onto a script, or ??? Some other way than one at a time when I have multiples ready.

Thank you again for all your help.

7

Happy to help,
There’s a relatively easy way to refresh specific films in a Plex Player like the hosted web app or Plex for Mac using the Select Multiple maneuver :

  • [1,2,3] Library - All - Mouseover a poster (like Barry Lyndon) to see the upper left circle

Library-All-Mouseover
Library-All-Mouseover707×463 242 KB

  • [4,5,6,7] Select posters - Click 3 dots - Choose Refresh Metadata

Selections-3dots-Refresh
Selections-3dots-Refresh1600×1143 304 KB

I’m a bit rusty at adding pictures of the right size and resolution,
HTH

1 Like
8

Thanks but sorry, you misunderstand.

I use folder navigation to find my media within Plex. The “library” of media was created long before I ever heard of Plex and its primary use is not for Plex. We use Plex Roku app to play anything we want to watch, and we find it using “browse by folder”.

There is no metadata refresh option on a folder in Plex web. And there are no “collections” in Plex since the files are not organized that way.

I have been refreshing individual media right before we watch it, if I have just placed a .SRT file with it. It’s not horrible but if I know I’m going to watch six things and I have put six .SRT files on disk, would be nice to have a way to say “just update these six”. Since they’re likely to be in only one or two folders, a script that updates only what’s in a folder would be quick. Hope that clears it up.

9

yeah i noticed that a few days ago when you first posted.
lets hope we can find a way still

10

You can use the API to do this: https://developer.plex.tv/pms/#tag/Library/operation/librarySectionPostRefresh

This call takes an optional path query parameter.

1 Like
11

Thanks for all your help. I still try your latest scanner experiments as soon as I can.

12

Thank you for this info. Sadly I have no idea how to understand or implement that documentation. Does it refer to creating a URL I type into a web browser? Completely n00b on that topic.

13

Hey so I learned a lot today about API calls, refreshing paths, trying to recreate your situation and your need to have external SRTs appear. Here’s what I found. For me, adding an external SRT gets it instantly associated with the media, without any hesitation or actions being performed. My logs show no activity, no delays, no refreshes, no scans. Let me explain…

  • I have a bunch of Korean films and found one that has Korean audio and only Chinese PGS subs embedded but also had an external English SRT I added years ago.
  • Based on my `Settings → Account → Audio & Subtitle Settings I prefer English Audio and to have English subs shown with foreign audio, as shown below:

Screenshot 2025-09-27 at 9.03.36 PM
Screenshot 2025-09-27 at 9.03.36 PM1023×298 41.6 KB

  • For the Korean film in question, The Battleship Island (2017), I have the following folder structure
/share/Video/Film
. /Korean
..  /The Battleship Island (2017)
...   /The Battleship Island (2017).eng.srt
...   /The Battleship Island (2017).mkv
  • When I remove the SRT file and put it in a directory Plex can’t access, the English subtitles are not available as a choice within Plex for Mac or Plex HTPC for Mac, and instead I see None as the choice for subtitles because I don’t prefer Chinese subs.
  • When I drop the English external SRT back into the directory, both Plex Players immediately switch the chosen subtitle to the English External SRT.
  • I did not have to Refresh anything for this to happen.
  • I did not have to Scan Library Files for this to happen.
  • This worked for me in Folder view or Movie view. Every time I hit play the choice was made automatically to show the English SRT.

So with my PMS server on Linux and my native Players on Mac, external subtitles automatically appear, based on my account settings, without any need for me to do API calls or scanner calls or GUI refreshes or anything at all. :slight_smile:

BTW if you want English subs shown always when subs exist for hearing reasons like my Dad does, regardless of audio language, you just have to change your account’s
Audio & Subtitle Settings → Auto Select Subtitle Mode to be set as Always Enabled
then hit the Save Changes button.

Good stuff. I’ll save the wall of text explaining how to use the API unless you’re curious :+1:
nibs

14

I can’t reply in much detail right now… I have should have time in a week or so to come back to this.

I have seen the behavior you describe, when a media was already known to have an .SRT file, you remove it (it can’t find it on disk so can’t show it) then put it back and voila it is available again. I believe you will have to do the ‘plex dance’ to completely remove all traces of that video file and .srt first. Then, put back the video file only, no .srt, and do a refresh/metadata refresh. Confirm Plex has no reference to any .srt. NOW put the .srt back (and ensure no automatic refresh/metadata refresh will run), and play the media, I don’t believe it will know anything about the .srt. file now.

I do have subtitles always enabled, as we do want to see them regardless of audio track language, same or different than .srt file. I’ve even named them with an invalid language code (like xx) or no language code at all, and after metadata refresh Plex for Roku app (the app we use to view) will offer them. So, our installation is working perfectly with the exception of needing a metadata refresh to pick up new .srt files.

I place the subtitle in the same directory with the media file, named the same except for .srt extension, and usually it does have a two-digit language code right before the extension (like .en). Keep in mind our directory doesn’t follow plex convention, another difference from your example. Also, our one library is using the Personal Media agent, could be yet another difference from your library. Don’t know if these are a factor or if you just need to do the plex dance first for your .srt experiment.

Also, just to mention, our Plex server is up to date - except for the very last update that I saw offered in the past week, I haven’t yet put that one up. Lubuntu 22.04 host is fully up to date.

I’ll be back within a week or so. Thanks.

15

This can be the very reason why external subtitles don’t get picked up or refreshed.

16

After a careful Plex Dance as you described, and following 99% of what you say to do, I get the same result. The SRT is automatically added, appearing on the Pre-play screen, is automatically chosen and gets played with the movie in Plex for Mac. I’m very careful to follow the Plex naming conventions and to use the Plex Movie agent and Plex Movie scanner.

The 1% anomaly: maybe just how you phrased it, but below is not the normal procedure:

When you add a new video, you Scan Library Files which causes a metadata refresh on the new item. I’ve never heard of adding something and doing a Refresh Metadata only. Very happy you mentioned your Plex Dance, though. I forgot to try that :slight_smile:

Screenshot 2025-09-28 at 9.08.56 AM
Screenshot 2025-09-28 at 9.08.56 AM1023×139 17.7 KB

17

Huh? That’s exactly what my post is about. I already have media a long time in Plex library. I find and add an .srt file and have to refresh metadata to pick it up.

18

I get that. The library isn’t meant for Plex but it’s nice that we can play its media by leveraging Plex and the Roku app.

Today I refresh metadata one at a time to pick up the .srt files. A bit tedious but not impossible. If I can’t find anything quicker I can continue. The refresh of entire library on our system takes a lot longer than we want to wait for, but that is also doable even though it is a waste of processing to just get say a dozen new files. So I was hoping to find a way to just refresh metadata for the contents of a folder.

19

I was referring to the very first step someone takes when adding a new film, using Scan Library Files.

What I can say is this. There are three ways to do a partial refresh (of only things that have changed):

  • You can do it by selecting one or more moves from their poster as I showed above.
  • You can do is using the API with the optional argument force=0
  • Or you can do it using the pscan method avoiding the optional
    -x, --force Force an operation (e.g. refresh).

I’ll spell out the API and scanner commands for a partial refresh in another reply. Everyone has their own wants, and I respect the amount of time you’ve put into making your PMS just that way you like. I’ll need you show us an exact example of your directory structure, though.

When showing us your directory structure, please use the Preformatted text style like I did when showing my folders. It’s an icon that looks like </> at the top of your reply compose window. It gets you monospaced font.

nibs

20

This is very normal and expected.
If you visit the item’s preplay page in a Plex client, usually external subtitles are also found and added.
But if you do not visit the preplay page and you need those subtitles for downloading or something, then you need to refresh metadata.

But you can also leave that to the Scheduled Task “Refresh local metadata every three days” – particularly if you added subtitles en-gros.