Your First xLights Show: A Step-by-Step Beginner Guide
This guide takes you from a new xLights show folder to a short sequence playing on one pixel prop. Start with one prop. Once it works, you can add more lights and music. This will be easier if you have a good overview of what’s going on in a light show — if you want a refresher, see our article on What exactly is a “Light Show”.
You’ll need: xLights on a computer (Mac, PC or Linux); one pixel prop or string; a compatible lighting controller and power supply (other option is a set of Twinkly lights, which include a controller and power supply); and Falcon Player (FPP) on a Raspberry Pi if you want to play the show without leaving your computer running. You can create and preview a sequence before the hardware is connected. Check our WS2811 Shopping List or Twinkly Shopping List for places to purchase.
1. Install xLights and create a show folder
xLights runs on Mac/Windows/Linux desktop or laptop computer, and is where you will create/program your light shows. Download xLights from the official releases page and install it. When you first open it, choose a show folder you can easily find again. xLights will keep your layout, controller configuration, and sequences there. You can have as many show folders as you like for different shows (Halloween vs Christmas, etc) — but let’s start with one.
Check: The folder name shown in xLights is the one you intend to use for this display (e.g. “Christmas 2026”)
2. Add your controller in xLights
For Twinkly devices, see our article on Twinkly Setup in xLights. For WS28XX devices, make sure your controller or is plugged in and set up and your xLights computer is on the same network with the controller. Open the Controllers tab. Click “Discover” — xLights should detect the controller and automatically populate settings. If you have questions on networking issues, see our article on Network Topology.
If xLights doesn’t auto-detect, choose Add Ethernet. Give it a recognizable name, then select its vendor, model, and variant if they appear in the list. Enter the controller’s actual IP address and choose the output protocol and other settings required by that controller. Enable Auto Layout Models so xLights can assign channels from your model and port layout. Save the controller settings.
If you do not have the controller yet, you can enter its details later and work in the preview for now. Before testing real lights, its IP address and output settings must match the physical controller.
Check: Your controller appears by name in the Controllers list. If it is connected to the same network, confirm that xLights can reach it (xLights will display a green light in the properties box of controllers it can see).
3. Add one prop to the layout
Open the Layout tab. Choose a built-in model for a simple shape, or import the .xmodel file supplied by your prop vendor. Place it in the preview, give it a clear name, and check its pixel count and wiring direction. Save the layout.
Simple Example: 50 pixel WS2811 string of lights that you want to test with:
- Go into xLights Layout tab
- Click the “single line” icon at the top
- In the layout field below the icons, click and drag where you want the line to be – location isn’t really important for testing
- Over on the left under the models tab, you should see an entry that says “single line”
- Click the single line entry under the models tab; rename the line to whatever you want
- The default size for a single line is 50 pixels, so you shouldn’t need to change anything — if you say have a 100 pixel string, set the “Nodes/String” to 100 (in xLights “Nodes” = “Pixels”)
For a purchased coro prop, follow the detailed WS2811 Prop Setup guide to import the model and use its wiring view.
Check: The model in xLights represents the number and order of pixels in your real prop.
4. Connect the prop to a controller port in xLights
Go back to Controllers, select your controller, and click Visualize. Find the prop in the model list and drag it onto the port where you will plug it in physically. Confirm that the model’s pixel count fits the port and that the Visualizer shows no configuration error. Save.
This assignment tells xLights which controller output drives the model. Adding a prop to the Layout preview alone does not make that physical connection.
Check: In Visualize, the prop appears on the same port you plan to use on the controller. Label that cable or record the port number so the physical wiring matches.
5. Send the configuration to the controller and test the lights
Connect the prop to its assigned port and power the controller using the equipment’s instructions. In the Controllers tab, select the controller and use Upload Input and Upload Output where those options are supported; some controller types do not need both. Then open Tools → Test, turn on Output to Lights, select your model, and run a test at modest brightness.
Check: The correct prop lights up, starts at pixel 1, and displays the expected colors. If it does not, check the physical port, model pixel count, wiring direction, controller IP address, and uploaded configuration before moving on.
6. Create a short sequence
Choose File → New Sequence. Pick Animation Sequence for a test without music, or Musical Sequence if you have an audio file ready. Use Quick Start, then open the Sequencer tab.
Find your prop’s row. Drag a simple effect, such as On or Bars, onto it and extend the effect for a few seconds. Add another effect in a different color. Play the sequence in the preview. If the prop is missing from the sequencer, use Edit Display Elements to add it to the sequence’s view.
Check: Both effects play on the correct model in the preview. With Output to Lights enabled (the light bulb icon in the sequencer), you can also check them on the real prop.
7. Save, render, and play through FPP
If you’re using FPP, make sure your Raspberry Pi is up and running on the same network and you can control FPP from a web browser on your computer. If you still need to set up FPP, see our article on How to Set Up FPP for Your First xLights Show, then come back here after you complete step 4 in that checklist.
Save the sequence with a clear name, such as First Prop Test. Choose Render All, then save again.
Open Tools → FPP Connect in xLights. Select your FPP device and the sequence, include the audio file if it is a musical sequence, and upload. In FPP, add the sequence to a playlist and play it.
Check: The prop plays the same effects through FPP that you saw in xLights.
What to do next
You now have the full path working: controller → assigned prop → tested lights → sequence → FPP. Add a second prop and assign it to its actual port before building a longer show. For controller specific settings, consult your controller’s instructions alongside the xLights controller guide. After you create a show you are happy with, go back to the How to Set Up FPP for Your First xLights Show article to learn how to schedule your shows to play automatically at set times.