Running Python scripts

• Introduction
• Check your Python command and version
• Install Python
• Try to run a script
• Diagnose an error
• Install modules with PDM
  • Install pipx
  • Install PDM
  • Install modules
  • Add new dependencies

Introduction

You can use GitHub search or this 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 is 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 that 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 need to use to run our 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 it has to be enabled 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?
   • If so, we'll fix that in the next section.
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 one of the standard library modules included with Python. 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

Use the command for your package manager (below, recommended).

Alternatively, use pip with the proper 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.

macOS

brew install pipx

Linux

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

Windows

scoop install pipx

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

Install PDM

Use pipx to install PDM.

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. (Our scripts contain boilerplate code to ensure the virtual environment gets loaded.)

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 that gave the ModuleNotFoundError error, above all the import statements, to ensure the virtual environment gets loaded.