Skip to content

Installation

You can either run Material Companion from one of the prebuilt packages, or build the application yourself.

Installing/Running Material Companion:

  1. Download the latest version from the releases page:
    • Windows: MaterialCompanion-win32-x64.zip
    • MacOS (Intel): MaterialCompanion-macos-x64.zip or MaterialCompanion-macos-x64.dmg
    • MacOS (Arm): MaterialCompanion-macos-arm64.zip or MaterialCompanion-macos-arm64.dmg
    • Linux: MaterialCompanion-linux-x64.zip
  2. Extract the file (if it's a .zip)
  3. Run Material Companion.exe (Windows) or Material Companion (MacOS/Linux) from within the folder, or open the .dmg file and drag Material Companion to the applications folder (MacOS)
  4. Material Plane users that want to use Material Compaion to update the Material Plane hardware you will need to install Python v3.

Some notes for MacOS users
On MacOS you will probably get a message that it can't be opened because the developer cannot be verified, or you might get an error stating “Material Companion” is damaged and can’t be opened. You should move it to the Trash.

To solve the first issue (unverified developer):

  1. Open 'System Preferences'
  2. Navigate to 'Security & Privacy
  3. Unlock the page using the lock in the lower left
  4. There should be a message: `"Material Companion" was blocked from use because it is not from an identified developer', press 'Open Anyway' to the right of that message
  5. You might get another message to confirm that you want to open it: click 'Open'

To solve the second issue ("Material Companion" is damaged):

  1. Open a Terminal window
  2. Run the following command: xattr -c "/Applications/Material Companion.app"
    Please note that if Material Companion is not located in the Applications folder you will have to modify the above command so it points to the correct location.

Connection issues with some browsers
Some browsers, such as Brave, have a built-in adblocker that may prevent Foundry from connecting to Material Companion. If you run into connection issues, try disabling the adblocker (in brave: press the lion icon, and set the shields to 'down'), or use another browser like Chrome or Firefox.

Running/Building from the source

If you want to make modifications, or you can't get the prebuild apps to work, you can try running or building the app from the source.

Prerequisites
You will need to install/configure the following applications:

Running from the source

  1. Download and unzip the source code
  2. Open a termial window and navigate to the Material Companion folder
  3. Run npm update and then npm install to update existing dependencies and install new dependencies
  4. Run npm start to start the app

Building from the source

  1. Make sure the app runs using the instructions above
  2. Run npm run package to build the app
  3. The apps should be built in /out/Material Companion-[platform]