Scripts let you automate tasks and add features OBS doesn't include by default

OBS supports two types of scripts: Lua and Python. A script is a text file that runs code inside OBS to do things like automatically switch scenes, create custom filters, send data to a website, or trigger actions when you go live. You write or download a script, place it in OBS's scripts folder, and enable it in the Scripts panel. Most scripts are free and shared by the streaming community.

The process differs slightly between Windows, Mac, and Linux, and you need to have Python installed on your computer if you want to use Python scripts. Lua scripts work without any extra software. If you've never written code before, you can still use scripts — thousands of ready-made scripts exist for common tasks like chat alerts, scene transitions, and stream info overlays.

Key Takeaways

  • Scripts go in your OBS scripts folder, which you can find and open directly from the Scripts panel in OBS.
  • Python scripts require Python to be installed on your computer; Lua scripts do not require any extra software.
  • You can download pre-written scripts from community sites or write your own if you know Lua or Python.
  • After placing a script in the folder, you enable it in the Scripts panel and configure any settings it offers.
  • If a script doesn't appear in the list, check that the file extension is correct and that OBS has permission to read the folder.

Finding and downloading scripts

The OBS Project maintains a list of community scripts on their GitHub repository at github.com/obsproject/obs-studio/wiki/Scripting-Guide. This page links to script collections and individual scripts organized by what they do. Popular community sites like Gist (gist.github.com) and Pastebin also host scripts that streamers share.

When you find a script you want, download the file to your computer. The file will have a .lua or .py extension depending on the language. Read the script's description or README file first — it will tell you what settings you need to configure and whether it requires any extra software or API keys. Some scripts need you to enter a Twitch API token or a webhook URL before they work.

Locating your scripts folder in OBS

Open OBS and go to Tools > Scripts. This opens the Scripts panel. At the bottom of the panel, you'll see a folder icon next to a path. Click that folder icon and your computer will open the scripts folder directly. This is where you place all your script files.

If you're on Windows, the folder is usually at C:\Users\[Your Username]\AppData\Roaming\obs-studio\scripts. On Mac, it's ~/Library/Application Support/obs-studio/scripts. On Linux, it's ~/.config/obs-studio/scripts. You can also navigate there manually if the folder icon doesn't work, but using the folder icon is faster and more reliable.

Installing Python for Python scripts

If you want to use Python scripts, you need Python installed on your computer. Go to python.org, download the latest version (3.9 or newer), and run the installer. On Windows, make sure to check the box that says "Add Python to PATH" during installation — this lets OBS find Python automatically.

After Python is installed, open OBS and go to Tools > Scripts. Click the Python Settings tab. If OBS found Python automatically, you'll see a path listed. If not, click the folder icon and navigate to your Python installation folder. On Windows, this is usually C:\Users\[Your Username]\AppData\Local\Programs\Python\Python[version]. On Mac and Linux, Python is usually already in the system path and OBS will find it without extra steps.

Adding a script file to OBS

Once you've downloaded a script and located your scripts folder, copy or move the script file into that folder. The file name doesn't matter, but the extension must be correct — .lua for Lua scripts and .py for Python scripts. If the file has a different extension like .txt, rename it to the correct one.

Go back to OBS and open Tools > Scripts again. Click the Loaded Scripts tab. You should see your script listed. If it doesn't appear, try clicking the refresh button (the circular arrow icon) at the bottom of the panel. If it still doesn't show up, check that the file extension is correct and that you placed it in the right folder.

Configuring script settings

When you select a script in the Loaded Scripts list, any settings it offers will appear below. These vary by script — some have no settings, while others let you enter API keys, choose colors, set delays, or pick which scenes to affect. Read the script's documentation to understand what each setting does.

Some scripts need you to enter sensitive information like API tokens or webhook URLs. Never share these settings with anyone. If a script asks for something you don't understand, check the script's GitHub page or documentation file for an explanation. Many scripts include a README or instructions file that walks you through setup step by step.

Troubleshooting scripts that don't work

If a script loads but doesn't do anything, check the OBS log file. Go to Help > Log Files > View Log. Search for the script's name or the word "error" to find messages about what went wrong. Common issues include missing API keys, incorrect file paths, or the script trying to access a scene or source that doesn't exist in your current setup.

If a script won't load at all, verify that the file extension is .lua or .py and that the file isn't corrupted. Try downloading it again. If you're using a Python script, make sure Python is installed and OBS can find it in the Python Settings tab. If a script causes OBS to crash, remove it from the scripts folder and restart OBS, then check the log file to see what caused the problem.

Writing your own scripts

If you know Lua or Python, you can write scripts to do exactly what you need. The OBS Scripting Guide at github.com/obsproject/obs-studio/wiki/Scripting-Guide documents all the functions available to scripts, like changing scenes, modifying sources, and reading settings. Start with a simple task — like logging a message when you go live — and build from there.

Many streamers start by modifying an existing script rather than writing from scratch. Find a script that does something similar to what you want, copy it, and change the parts you need. This is faster than learning the entire API at once. Share your finished script on GitHub or Pastebin so other streamers can use it.

Frequently Asked Questions

Do I need to restart OBS after adding a script?

No. After you place a script in the scripts folder, go to Tools > Scripts and click the refresh button. OBS will load the script immediately. You only need to restart OBS if a script crashes or if you're updating Python.

Can I use scripts on Mac and Linux, or just Windows?

Scripts work on all three. The scripts folder location is different on each system, but the process is the same. Some scripts may have platform-specific features or limitations — check the script's documentation to be sure.

What if a script asks for a Twitch API token?

Go to dev.twitch.tv, sign in with your Twitch account, and create a new application. Twitch will give you a token that you paste into the script's settings. Never share this token with anyone. If you think someone has seen it, go back to dev.twitch.tv and regenerate it.

Can I disable a script without deleting it?

Yes. In the Loaded Scripts tab, uncheck the box next to the script's name. It will stay in your scripts folder but won't run. Check the box again to turn it back on.

Where do I find scripts for specific tasks like chat alerts or scene switching?

Search GitHub for "OBS script" plus what you want to do, like "OBS script chat alerts" or "OBS script auto scene switch". The OBS Project's scripting wiki also lists popular scripts by category. Reddit communities like r/obs and r/Twitch often have recommendations for specific tasks.