Skip to content

Updating Moonshine

Moonshine downloads its own updates, for both the desktop app and the show machine. The two install them differently:

The desktop app The show machine
Checks for new versions Each time you start it Shortly after it starts, then every six hours
Downloads them Automatically, in the background Automatically, in the background
Installs them After asking you Only when someone chooses to, on the show machine itself or with Update in the app
What installing does The app closes and reopens Moonshine restarts, and every output goes black for a few seconds

This page describes Windows. A Mac show machine updates itself the same way if it was installed with Moonshine 0.3.19 or later (see On a Mac).

The desktop app updates itself

The desktop app checks for updates each time it starts, right after it connects to the show machine, and downloads any newer version in the background.

When the download finishes, this dialog appears over the app window:

Moonshine update

Moonshine 0.3.0 is ready to install.

The viewer will close and reopen. Your show machine is not affected.

Button What happens
Restart now The app closes, installs the update and reopens
Later Nothing for now. The update installs the next time you close the app

If the check fails, for example because the venue has no internet, the app doesn't show an error.

A new app does not bring new features

The app displays the interface that the show machine serves. Updating the app doesn't affect the show machine, and the two don't need to run the same version. New features arrive when you update the show machine.

Older portable copies don't update

Builds before 0.3.5 were a single portable .exe that can't update itself. Such a copy keeps working on the version you downloaded. Install the current app from download.moonshine.software, and it will update itself from then on.

Browsers need no updates. A browser loads the current interface from the show machine each time it connects.

After the show machine is updated, any app or browser that was already open reloads onto the new version. If you have unsaved changes or are in the middle of an edit, it waits and shows a Reload now button instead.

Updating the show machine

The show machine checks for updates and downloads them, but it doesn't install them until someone chooses to. Installing restarts Moonshine, and everything the machine projects goes black until TouchDesigner has started again.

On the show machine's own screen

When the download finishes, the show machine asks on its main display:

Moonshine update

Moonshine 0.3.20 is ready to install. This machine runs 0.3.19.

Installing restarts Moonshine, so every output goes dark for a few seconds.

[ Install ] [ Later ]

The show keeps running while the question is on screen. It's asked once per version each time Moonshine starts. Later, Enter and Esc all close it without installing, so a stray key press can't restart a show. The banner in the app still offers the same update.

The question doesn't appear when the machine's main display is itself a projector output, because the audience would see it. Install from the app instead.

The banner

When there's an update to report, a strip appears under the tabs in every signed-in browser and app, with the version the machine is running beside the message:

Moonshine 0.3.0 is ready to install · running 0.2.0 [ Update ] ✕

The update strip under the top bar: Moonshine 0.4.1 is ready to install, running 0.4.0, with Release notes, Update and a dismiss button

When the release has notes, Release notes opens them.

✕ hides the current message. The banner comes back when the message changes, so dismissing is available doesn't hide is ready to install when it arrives. A download percentage going up doesn't count as a change, so a dismissed download stays hidden. Reloading the page brings the banner back.

What it checks, and when

The show machine checks Moonshine's download site for the newest version shortly after it starts, then every six hours. If a check fails, it tries again after fifteen minutes.

Every download is verified against the release, and verified again just before it's installed. A download that doesn't match is discarded.

Apart from Check again after a failed update, you can't start a check by hand, and there's no setting to turn checking off. A show machine without internet access fails the check and shows nothing.

What the banner can say

The banner says What's happening What to do
Moonshine 0.3.0 is available A newer version exists and this machine is entitled to it. The download has already started Nothing. Wait
…is downloading — 42% The update is downloading (around 15 MB) Nothing. The show isn't affected
…is ready to install Downloaded and verified. This is the only state with an Update button Install it when you're not in a show
…is out, but this license's updates ran to 2026-06-01 The build was released after your license's update window closed See below
…is out, but that release has to be installed by hand The release doesn't include an installer this machine can run on its own Use the Downloads link and install it at the machine
…needs a newer TouchDesigner on the show machine The release is built for a newer engine than this machine has See below
…could not be installed: reason An update was found, then failed Click Check again

The last four messages are amber. None of them has an Update button, because the machine would refuse the install.

A failed check never draws a banner

A background check that can't reach the internet is only written to the log, so a closed show network doesn't show a constant warning. A banner appears only when an update to a specific version fails, such as a broken download or a refused install.

Downloads are kept until you install

The download is stored in the show machine's data folder, which updates don't touch. If the machine restarts, or you wait until tomorrow, the file on disk is verified again and reused. A download that stalls is abandoned after fifteen minutes and retried.

Installing

Install on the show machine and Update in the app do the same thing. Update appears only when an update is ready to install, and it asks you to confirm:

Install this update?

The show machine will install Moonshine 0.3.0 and restart. Outputs go dark until it comes back, and every connected browser will reconnect on its own.

[ Not now ] [ Install and restart ]

The Install this update? confirmation, explaining that the outputs go dark until the show machine is back, with Not now and Install and restart

When you confirm:

  1. The show machine verifies the download again and checks that something will start Moonshine afterwards (see the warning below). If either check fails, the update stops. A download that has changed since it was verified is deleted.
  2. It keeps a copy of the current version in the data folder, writes the new version in its place, and verifies it. If that fails, it puts the old version back and doesn't restart.
  3. About a second later, TouchDesigner quits. Every output goes black, and every browser and app loses its connection.
  4. Moonshine starts on the new version and reopens the project it had open. Browsers and apps reconnect on their own, retrying at least every 30 seconds until the machine answers.

No installer runs, so Windows doesn't ask for administrator approval.

Machines installed before 0.3.19 update through the installer

So does any release that changes something only the installer can change, such as a firewall port. The show machine runs the installer silently and quits. Windows may ask an administrator to approve it, and only Owlette brings Moonshine back afterwards. Run the current installer once at the machine, and later updates use the faster method above.

Never press Update during a show

From the moment TouchDesigner quits until it has restarted and reloaded your project, that machine projects nothing. Once the install has started, you can't cancel it or roll it back. Update at load-in or before the day starts, never between cues or with an audience in the room.

Anyone signed in can press it

Update isn't limited to administrator accounts. Everyone signed in to this show machine, on any device, sees the same banner and the same button. If that matters on your job, tell the crew before doors.

Know how your machine comes back

Moonshine starts itself again after an update:

  • With Owlette (a separate product the installer offers when it finds it), Owlette restarts it.
  • Without Owlette, Moonshine starts a small helper before it quits, which reopens Moonshine once it has closed.
  • On a Mac, its login agent restarts it.

An update that goes through the installer (see the note above) is different: only Owlette restarts Moonshine afterwards. Without Owlette, someone has to start Moonshine from the Start menu. Find out which applies to your show machine before you rely on Update at a venue that's hard to get back to.

What an update keeps

Everything you've made. Projects, media, masks, warps, user accounts, the license and the machine's certificate are stored in the show machine's data folder, and updates leave that folder alone. Uninstalling leaves it in place too, along with the snapshots folder beside it, where the machine keeps its snapshots. You don't need to enter your license key again, and the machine reopens the project it was running.

On a Mac

  • The show machine updates itself as described above if it was installed with the Moonshine 0.3.19 package or later. An older install, or a release that needs the package, shows …is out, but that release has to be installed by hand, with a link to the downloads page and nothing to press. Download the new package and run it on the Mac. It stops Moonshine, installs the new version over the old one, leaves the data folder alone, and starts Moonshine again.
  • The desktop app updates itself as it does on Windows: it checks when it starts, downloads in the background, and asks before it restarts.

When your license blocks a build

A Moonshine license covers new builds released up to a certain date, called its update window. A build released after that date isn't covered, and the license can't install it.

When this happens, the banner says so and shows the date:

Moonshine 0.4.0 is out, but this license's updates ran to 2026-06-01 Downloads ✕

There's no Update button. Your license is fine, and you have three options:

  1. Carry on. Builds you already run keep working forever. The update window only limits which new builds you can install.
  2. Install the newest build inside your window. The Downloads link opens the downloads page, where you'll find it.
  3. Renew your updates with Tridant to get the newer build.

The release date is what counts

Moonshine compares the date a build was released with your window. The date you install it doesn't matter, so a build released inside your window is still yours to install a year later.

After renewing, restart Moonshine

The show machine reads its license from Tridant once a day, so a renewal clears the banner within a day. The blocked banner has no Check again button. To update sooner, restart Moonshine on the show machine, which reads the license and looks for the release right away. An administrator can restart it from any browser with Settings → Admin → Server → Restart Moonshine Server (see Restart).

Do not install a build past your window by hand

Installing a newer build by hand gets past the banner, but your license still doesn't cover it. Moonshine won't run it, and shows This Moonshine build is no longer supported with no key field, because the key isn't the problem. See When the build itself is out of date.

When a release needs a newer TouchDesigner

Moonshine runs on Derivative's engine, and each release is built for a specific engine build (see What you need). When a release needs a newer build than the show machine has, the banner says so and offers nothing to press.

Moonshine checks this before it downloads anything. An older engine that opens a file written by a newer one can fail without showing any error, which you don't want to discover during a show.

To update, run the full installer from download.moonshine.software at the machine. It detects which engine build is installed and offers to download the right one from Derivative (about 2.9 GB) before it installs Moonshine. A self-update can't do this step.

The line on the show machine's own screen

The show machine's display shows a status panel, and the updater adds a line to it when there's news:

Update: v0.3.0 available
Update: v0.3.0 downloading 42%
Update: v0.3.0 blocked - updates ran to 2026-06-01
Update: v0.3.0 available - install it by hand
Update: v0.3.0 needs a newer TouchDesigner
Update: v0.3.0 failed - the download timed out

There's no line when everything is up to date. The panel doesn't take clicks. The question on the machine is a separate dialog, shown once when the update is ready.

When an update fails

The banner says What it means What to do
the download could not reach the server The machine lost its internet connection during the download Check the machine's internet connection. It retries in fifteen minutes
the download timed out The download took longer than its fifteen-minute limit Usually a slow venue connection. It retries automatically
the download did not match the release manifest The file that arrived doesn't match the release, so it was discarded Click Check again. If it keeps happening, something on that network is altering downloads: ask the venue's IT team
the download could not be written to disk The drive is full or read-only Free up space on the drive Moonshine is installed on
The downloaded update is gone. Run a check again. (or installer) The file was removed between the download and the install Click Check again
The downloaded update no longer matches the release manifest and has been deleted. (or installer) The file changed after it was verified, so Moonshine deleted it Click Check again to download a clean copy
…did not verify after writing. The previous project file was put back. Writing the new version failed, so the running version was restored and nothing restarted Click Check again. If it keeps happening, check the drive Moonshine is installed on
Nothing on this machine would start Moonshine again… Moonshine found no way to start again after quitting, so it kept running Install Owlette, or install by hand from the downloads page
This machine cannot replace its own project file… The install is older than 0.3.19, or its file permissions were changed Run the current installer once at the machine
The installer would not start Windows wouldn't launch the installer, usually because of antivirus software Install by hand from the downloads page

Check again asks the show machine to check now. You can press it three times in a row, then once a minute. Extra presses show the current status.

Where to go next