Package
Instamix accepts two kinds of package. Pick the extension format for plain files and the project format for anything that ships a Python package or depends on one.
Extension: .fontlabext
An extension is a folder named with a reverse-DNS id, such as com.example.hello.fontlabext. It holds a manifest.fontlabextj at its root and the files the manifest names:
com.example.hello.fontlabext/
├── manifest.fontlabextj
├── scripts/
│ └── Hello.py
└── encoding/
└── hello.enc
{"id": "com.example.hello", "name": "Hello", "version": "1.0.0",
"min_fontlab": "9.0",
"install": [{"from": "scripts", "to": "Scripts/{}"},
{"from": "encoding/*.enc", "to": "Encoding/{}"}]}
Each install entry copies or links the files under from into to. A destination starts with a target: Scripts, Actions, Codepage, Data, Encoding or site-packages, in any case. . is the target root, {} is the extension name without .fontlabext, and {var} is a value from the manifest's vars. Unknown variables, unknown targets, .. and unknown manifest keys (other than this_file) are errors, so a typo fails the install instead of placing files in the wrong folder.
A manifest can also name Python packages and requirements:
"python": {"requires": ["fonttools>=4"], "packages": ["src/hello"]}
Wrap a single script
You do not need to write the manifest by hand for a script:
fontlab-instamix wrap CountGlyphs.py --id com.example.countglyphs \
--name "Count Glyphs" --version 1.0.0 --out dist --zip
This writes dist/com.example.countglyphs.fontlabext with the script under scripts/ and a manifest that installs it into Scripts/com.example.countglyphs/. --zip also writes dist/com.example.countglyphs.fontlabextz. wrap accepts .py and .vfpy files, or a folder of them.
Zip: .fontlabextz
A .fontlabextz is a zip that holds one or more .fontlabext folders. Use it to send extensions as one file. Instamix refuses members with absolute paths, drive letters or ... An install.vfpy hook inside a zip runs only when the user passes --run-hooks.
Project: [tool.fontlab-install]
A project is an ordinary Python repository. Add a table to pyproject.toml:
[project]
name = "fontlab-my-tools"
version = "0.2.0"
[tool.fontlab-install]
id = "com.example.mytools"
name = "fontlab-my-tools"
packages = ["src/mytools"]
scripts = "Scripts"
extensions = "Extensions"
dependencies = ["fonttools>=4.50"]
idis required and must be reverse-DNS. It names the extension record and the uninstaller.nameshould be the distribution name from[project].name. Instamix uses it for the<name>-<version>.dist-infofolder it writes into site-packages.packageslists package folders to place in<data>/python/3.11/site-packages.scriptsis a folder whose subfolders become FontLab Scripts menu folders.Scripts/MyTools/SayHello.pyinstalls asScripts/MyTools/SayHello.py.extensionsis a folder of plugin bundles (<kind>/<Name>.fontlab<Kind>).dependenciesare PEP 508 requirements. Instamix installs them with uv, evaluating markers for Python 3.11 on the host system. A dependency on another FontLab project that is checked out beside yours is installed from that checkout.
Instamix skips __pycache__, *.pyc, *.vfpyc and .DS_Store. It reads the version from [project].version, a hatch-vcs version file, PKG-INFO or git describe, in that order.
The install.vfpy stub
Users install a project by opening install.vfpy in FontLab. Write the stub with:
fontlab-instamix stub .
The stub imports an installed instamix 1.0.13 or later. If there is none, or the installed one is older, it uses a sibling fontlab-python-instamix checkout, or downloads the instamix wheel from PyPI and checks its SHA-256. If that fails, the older copy is put back. Then it installs the project and shows a message with the id and version. Commit the stub; rerun stub --force to update it.
Which to choose
| Need | Format |
|---|---|
| One script or a few | wrap → .fontlabextz |
| Encodings, codepages, actions, data files | extension with a manifest |
| A Python package for other scripts to import | project |
| Plugins (reporters, filters, tools, palettes) | project with extensions |
| Dependencies from PyPI or other FontLab projects | project |