Quick Start

Quick start: install and launch MoleditPy

Home · Quick start · Illustrated tutorial · 日本語

Start here for a fresh installation. You need Python 3.9–3.14 and a graphical desktop. If Python is missing, follow Installing Python and pip first.

On this page

• Choose an installation
• Windows: PowerShell
• macOS and Linux: Terminal
• What happens in the installer?
• Check the installation
• Update or remove
• If something fails

Choose an installation

Your goal	Route
Python environment, plugins, and package updates	Install moleditpy-installer below; it selects the correct app package for your OS
Windows application without setting up Python	Windows standalone installer
Apple Silicon application without setting up Python	macOS standalone bundle
Container environment	Docker guide; a working GUI/display connection is still needed

The standalone Windows/macOS packages omit Open Babel and pip. Plugins that need additional Python packages require a Python-based installation instead.

Windows: PowerShell

Run these two lines in order in a terminal. Creating a virtual environment is not a required first step.

pip install moleditpy-installer
python -m moleditpy_installer

The first line also installs the application automatically. The second configures shortcuts and file associations.

macOS and Linux: Terminal

pip install moleditpy-installer
python -m moleditpy_installer

If your Python command is named python3, use python3 -m moleditpy_installer for the second line. Use pip and python from the same Python environment.

A virtual environment is an option when needed. If Linux reports externally-managed-environment, follow the virtual-environment instructions in Python and pip troubleshooting, then run the same two lines inside it.

Debian/Ubuntu may also need sudo apt install libxcb-cursor0 for Qt. For python.org Python on macOS, run Install Certificates.command. See the Windows, macOS, and Linux pages for platform details.

What happens in the installer?

The installer opens an interactive terminal interface. Choose components, then press Install. Defaults are application-menu entry on, .pmeprj association on, Desktop shortcut off, and per-user scope. It creates a launcher; it does not replace the Python environment.

Both installer launch commands below are supported:

python -m moleditpy_installer
moleditpy-installer

Prefer python -m moleditpy_installer: it uses the Python you selected even when the moleditpy-installer command is missing from PATH. Install into that same interpreter with pip install moleditpy-installer. The package name uses a hyphen; the Python module uses an underscore. If multiple Python versions are installed, python -m pip install moleditpy-installer can target the Python used for the installer.

For scripted installation, append --no-tui. Other useful options are --desktop, --check, --exe-path, and --uninstall:

python -m moleditpy_installer --check
python -m moleditpy_installer --no-tui --desktop
python -m moleditpy_installer --help

Check the installation

Run the environment's moleditpy command with --version, then launch with --safe if you want to check the built-in editor without plugins:

moleditpy --version
moleditpy --safe

If you chose to use a virtual environment, activate it before running these commands.

Safe mode skips all plugin loading. It keeps the built-in 2D drawing, 3D conversion, measurement, and export tools available. Start normally to use plugins. If the app opens, continue with Your first molecule, an illustrated walkthrough.

Update or remove

Activate the same environment before using these commands; or substitute its explicit Python path:

# Windows/macOS
python -m pip install --upgrade moleditpy moleditpy-installer
# Linux
python -m pip install --upgrade moleditpy-linux moleditpy-installer
# Refresh the launcher after an environment/path change
python -m moleditpy_installer

Before removing the environment, remove its launchers and associations with python -m moleditpy_installer --uninstall. This does not uninstall the app package. Use python -m pip uninstall moleditpy (Windows/macOS) or python -m pip uninstall moleditpy-linux (Linux) to remove the app itself.

If something fails

Symptom	Next step
moleditpy-installer is not recognized	Use the selected interpreter with -m moleditpy_installer
No module named moleditpy_installer	Install with that exact interpreter's -m pip; a different Python may hold the package
Installer cannot locate MoleditPy	Use --check, then --exe-path with the environment's moleditpy executable or Scripts/bin folder
Window crashes or 3D is blank	Try --safe, then follow Troubleshooting; safe mode does not replace graphics drivers
Linux package conflict	Use moleditpy-linux; the installer selects it automatically