Running Python scripts - musescore/MuseScore GitHub Wiki

Introduction

Use GitHub search or this Terminal command to list all Python scripts in MuseScore's repository:

git ls-files "*.py" ":^*thirdparty/*"

We use these scripts locally and in CI jobs to:

  • Upload/download files
  • Manipulate data (e.g. convert to different formats)
  • Run sanity checks (e.g. on translations)
  • Generate C++ code

Some scripts produce output that's used in the build process of MuseScore Studio. However, this output is usually checked into the repository as JSON, XML, or C++ files, which means most developers never need to run the Python scripts.

Check your Python command and version

If you want to run one of our Python scripts, you'll need a recent version of Python.

Try all of these commands to see which version(s) you have available, if any:

python3 --version
python --version
py -3 --version

If one of these commands reports Python version 3.9 or higher, that's the command you should use to run our Python scripts.

If they all report lower versions, or give command not found errors, then you need to install a more recent version.

Install Python

If you need to install Python, use the commands for your package manager.

macOS

brew install python

Linux

Python should be preinstalled unless you're using a minimal environment like Docker, in which case you can install it with:

sudo apt install python3
sudo dnf install python
sudo pacman -S python3

If your distribution's version of Python is too old, you could:

  • Install pyenv and use it to install a newer Python.
  • Install Python from a third-party repository (e.g. deadsnakes PPA).
  • Upgrade to a more recent version of your distribution.

Windows

choco install python # Admin prompt or sudo required
scoop install python

On Windows, we recommend that you enable Python's UTF-8 mode, otherwise you're likely to encounter text encoding errors when reading and writing files. This mode will be enabled by default in Python 3.15 (not yet released), but you have to enable it manually in earlier versions.

To enable Python's UTF-8 mode:

  1. Press the Windows key 🪟 to open the Start menu.
    1. Search for "edit environment".
    2. Select Edit environment variables for your account.
  2. The Environment Variables dialog should appear.
    1. Under User variables for [your name], click New.
    2. Enter variable name PYTHONUTF8 and value 1 (i.e. PYTHONUTF8=1).
    3. Click OK twice to dismiss both dialogs.
  3. Close your prompt/terminal and re-open it to load the new environment.

Try to run a script

Once Python is installed and you know which command to use, you can try running a script.

# Use the Python command that gave suitable output with --version
python3 path/to/script.py
python path/to/script.py
py -3 path/to/script.py

For example, if you're using python3 as the command, and you're trying to run the update_instruments_xml.py script that's located in share/instruments:

python3 share/instruments/update_instruments_xml.py

This may work, or you may get an error.

Diagnose an error

If you get an error running one of our Python scripts:

  1. Was it ModuleNotFoundError?
  2. Does the error message tell you what to do?
    • If so, try doing it.
  3. Open the script file in a text editor. Can you find the error message in this file?
    • If so, look at the surrounding code and try to figure out what caused the message to appear.
  4. Paste the error message into a search engine. Are any of the results useful?
    • You may find someone else has encountered the problem and posted a solution (e.g. on GitHub or Stack Overflow).

If you're still stuck, ask for help in the Discord server's #development channel or open an issue on our repository.

Install modules with PDM

When running a Python script, you may encounter a ModuleNotFoundError, such as:

ModuleNotFoundError: No module named 'requests'

This happens when a script tries to import a module that's not in the Python standard library (i.e. modules that come included with Python). It means the module needs to be installed separately.

How we used install modules (click to show/hide)

In the past we used Python's package manager, pip, to install the module from the Python Package Index (PyPI):

pip install requests  # Don't do this!

However, this is no longer recommended because it can lead to "dependency hell" where different modules depend on different versions of other modules.

Instead, Python recommends that you create a virtual environment and install modules within it, like this:

python3 -m venv .venv                # Create folder called '.venv' & set up virtual environment inside.
.venv/bin/pip install requests       # Install a module into the virtual environment.
.venv/bin/python path/to/script.py   # Run a script with access to virtual environment's modules.

Note: Python provides .venv/bin/activate scripts that you can source to "activate" the virtual environment in your current shell. Once activated, you can type python and pip instead of .venv/bin/python and .venv/bin/pip. Type deactivate to return to the normal shell. The bin folder is called Scripts on Windows!

Modules installed in the virtual environment are isolated from the rest of your system, which means they cannot break your main Python installation. However, the virtual environment itself can still break if conflicting modules are installed within it.

To reduce the chances of this happening, Python recommends that you create separate virtual environments for each Python program you run, so each virtual environment only has to contain the specific modules needed for that program. Tools like Pipenv and pipx exist to make this easier for libraries and applications respectively.

Nevertheless, conflicts are still possible. Internally, Pipenv and pipx rely on pip to install modules, and pip isn't clever enough to resolve certain kinds of dependency conflict. Poetry and PDM were created to handle these situations, with PDM being the newer of the two and having the edge in terms of reliability and performance.

These days we use PDM to manage installation of Python modules. To get PDM, first you need to install pipx.

Install pipx

pipx installs Python programs in isolated environments to avoid breaking other Python packages.

To install pipx, use the command for your native package manager (recommended), or use the cross-platform method with pip (not recommended).

macOS (recommended)

brew install pipx

Linux (recommended)

sudo apt install pipx
sudo dnf install pipx
sudo pacman -S python-pipx

Windows (recommended)

scoop install pipx

Note: Chocolatey doesn't have a pipx package so you'll have to use scoop or pip (below) to install pipx.

All platforms (not recommended)

Alternatively, use pip with the appropriate Python command.

# Use the Python command that gave suitable output with --version
python3 -m pip install --user pipx
python -m pip install --user pipx
py -3 -m pip install --user pipx

If using pip, you may need to add --break-system-packages. That's acceptable in this case because the purpose of pipx is to avoid breaking system packages.

Install PDM

By design, pipx only installs Python programs, not modules. To install modules, we recommend PDM.

Use pipx to install PDF safely inside its own isolated environment:

pipx install pdm

Install modules

Run this command in MuseScore's source directory:

pdm install

This creates a virtual environment (.venv folder) and installs the dependencies mentioned in MuseScore's pyproject.toml file.

Now you can try to run a script again. You shouldn't get ModuleNotFoundError this time.

Note

Our scripts contain boilerplate code to ensure the virtual environment gets loaded.

If a script lacks the boilerplate, you can load the venv manually with pdm run, like this:

pdm run path/to/script.py

Add new dependencies

If you encounter another ModuleNotFoundError in the future, simply run pdm install again to install any new dependencies that have been added to pyproject.toml in the meantime.

If that didn't work (e.g. because you added a new import statement in a Python script), use this command instead:

pdm add <module>  # replace '<module>' with the name of the missing module or PyPI package.

This installs the module to your own virtual environment and also modifies the pyproject.toml and pdm.lock files in the repository. You should commit the changes to those files so that other developers can pick up the new module with pdm install.

You may also need to add the boilerplate code to the top of the script file that gave the ModuleNotFoundError error, above all the import statements, to ensure the virtual environment gets loaded.

Add a custom footer
⚠️ **GitHub.com Fallback** ⚠️