Install problems, message by message

When the setup cannot go on, the launcher says why in plain words and stops. Find your message below. If none matches, run the launcher from a terminal so that the window stays open, and read the last lines. On Windows: open the app folder, click the address bar, type cmd, press Enter, then type start.bat. On a Mac: open Terminal, type cd and a space, drag the folder onto the window, press Enter, then type ./start.command.

Python

“Python was not found on this PC”

Windows. Press Y to let the launcher install Python 3.12. If you press N, install Python 3.12 from https://www.python.org/downloads/, tick “Add Python to PATH”, close the window, and start again.

“Found Python 3.13, but MeshOptimiser needs Python 3.10, 3.11 or 3.12”

Your Python is too new for the CAD reader. Let the launcher install 3.12 next to it, or install 3.12 yourself. Both versions can stay.

“Auto-install failed”

Windows. Both ways of installing Python failed, usually for lack of an internet connection or because of a restriction on the computer. Install Python 3.12 by hand and start again.

“Python was installed but is not yet visible on PATH”

Windows. The install worked, but this window does not know yet. Close the launcher window, open the folder again, and double-click start.bat once more.

“python3 is not installed” or “Homebrew is available - installing Python 3.12”

macOS. The first means no Python was found and Homebrew is not there either: install Python 3.12 from python.org or install Homebrew, and start again. The second is the launcher doing it for you; wait for it.

“That did not give a usable Python”

macOS. Homebrew ran but there is still no supported Python. Install Python 3.12 from https://www.python.org/downloads/ and double-click start.command again.

The Python environment

“Failed to create virtual environment”

The venv part of Python is missing, or the folder is not writable. Move the app folder to somewhere you may write to, such as Documents, and make sure a normal Python from python.org is installed.

“The Python environment in the .venv folder no longer works”

The Python it was made from has been removed or replaced. Delete the .venv folder and start again.

“The environment in the .venv folder was made with the Python above”

An older environment, made with a version outside 3.10 to 3.12. Delete the .venv folder and start again.

“Detected a non-macOS .venv (probably built on Windows). Rebuilding...”

Not a problem: the folder came from a Windows computer, and the launcher is making a new environment for the Mac.

“ModuleNotFoundError: No module named ‘OCP’”

The environment is incomplete. Delete the .venv folder and start again. The same goes for a missing numpy or trimesh.

Downloading the add-ons

“ERROR: pip install failed”

The add-ons could not be downloaded. Check your internet connection, check that Python is 3.10 to 3.12, and check that the drive has about 2 GB free. Then start again: the launcher picks up where it stopped.

Slow or stuck at “Installing dependencies”

The CAD reader is a large download. On a slow connection it takes longer than the three minutes mentioned. Let it finish. If nothing has moved for more than ten minutes, close the window, delete the .venv folder and start again.

A network that needs a proxy

The installer that downloads the add-ons (pip) reads the standard HTTPS_PROXY setting. In a terminal opened in the app folder, set it first, then run the launcher. On Windows: set HTTPS_PROXY=http://your-proxy:port. On a Mac: export HTTPS_PROXY=http://your-proxy:port. Your network administrator knows the address.

The app does not open

The window does not appear, but the launcher window says it is running

Look at the address in the launcher window and open it in a browser by hand. Normally http://localhost:4242.

The address is not localhost:4242

Something else on your computer was using that number, so the server picked another one. This is fine. The launcher prints the address it chose. You can also ask for a number yourself, from a terminal opened in the app folder: ./start.command --port 5000 on a Mac, .venv\Scripts\python serve.py --port 5000 on Windows.

“Operation not permitted” on a Mac

Right-click start.command, choose Open, and confirm. Only needed once.

An empty page, or “This page needs a local server”

The page was opened straight from the file, or the server is not running. Start the app with its launcher. Do not open index.html by double-clicking it.

“MeshOptimiser stopped with an error”

Windows, when started with start_hidden.vbs. Double-click start.bat instead, which shows what went wrong.

Starting with a file

“ERROR: file not found”

The path you gave does not exist. Drag the file onto the launcher instead of typing the path.

“Unsupported file type”

Starting the app with a file works for .step, .stp, .glb and .gltf. Open the other formats from inside the app.

“keeps part of the model in separate files”

A .gltf that has its geometry or textures in files beside it cannot be handed over as one file. Save it as a single .glb, or open it from inside the app.

Still stuck?

Report a problem on the website. Say which system you use, which version of Python the launcher printed, and paste the last lines of the launcher window into the form; it packs them into one file you can send. See Troubleshooting for problems that come after the install, such as an empty 3D view or a slow conversion.