Using third-party Python packages

Mach and its associated commands have a variety of 3rd-party Python dependencies. Many of these are vendored in third_party/python, while others are installed at runtime via pip.

The dependencies of Mach itself can be found at python/sites/mach.txt. Mach commands may have additional dependencies which are specified at python/sites/<site>.txt.

For example, the following Mach command would have its 3rd-party dependencies declared at python/sites/foo.txt.

@Command(
    "foo-it",
    virtualenv_name="foo",
)
# ...
def foo_it_command():
    import specific_dependency

The format of <site>.txt files are documented further in the MachEnvRequirements class.

Adding a Python package

There’s two ways of using 3rd-party Python dependencies:

• pip install the packages. Python dependencies with native code must be installed using pip. This is the recommended technique for adding new Python dependencies.

• Vendor the source of the Python package in-tree. Dependencies of the Mach core logic or of building Firefox itself must be vendored.

Note

For dependencies that meet both restrictions (dependency of Mach/build, and has native code), see the Mach/Build Native 3rd-party Dependencies section below.

pip install the package

To add a pip install-d package dependency, add it to your site’s python/sites/<site>.txt manifest file:

...
pypi:new-package==<version>

If you’d like to lock dependencies and validate hashes, you can alternatively specify a path to a requirements.txt file:

...
requirements-txt:path/to/requirements.txt

The requirements.txt file can be generated using any tool you like, but it must include hashes for all listed packages.

Note

Some tasks are not permitted to use external resources, and for those we can publish packages to an internal PyPI mirror. See how to upload to internal PyPI for more details.

Vendoring Python packages

To vendor a Python package run ./mach vendor python --add <package>~=<major>.<minor>. This will add your dependency to third_party/python/pyproject.toml then begin the re-vendoring process for all dependencies. The pyproject.toml is used by uv to create a lockfile (uv.lock) that ensures all the dependencies are compatible. This lockfile is then used to generate a