Vivarium Build Utils contains shared build utilities for Simulation Science projects.

Supported Python versions: 3.10, 3.11, 3.12, 3.13

You can install vivarium-build-utils from PyPI with pip:

pip install vivarium-build-utils

or build it from source by cloning the monorepo and installing this package:

git clone https://github.com/ihmeuw/vivarium-suite.git
cd vivarium-suite/libs/build-utils
conda create -n ENVIRONMENT_NAME
pip install -e .

Overview

This repository provides:

  • `vars/`: Jenkins shared library functions for continuous integration pipelines

  • `resources/`: Shared Makefiles and build scripts for consistent build processes

Note: for help with the Make targets available to any environment with this repository installed, run make help in the terminal.

Monorepo support

vivarium-build-utils supports both standalone repos and monorepos where many packages live under libs/<pkg>/. Standalone repos keep working with no changes; the sections below describe what’s needed for a monorepo.

Top-level Jenkinsfile (provisioner)

The monorepo’s root Jenkinsfile calls monorepo() to provision a Multibranch Pipeline for each per-package Jenkinsfile. Run this on the default branch only:

@Library('vivarium_build_utils') _

monorepo(
    jenkinsfiles: [
        'libs/core/Jenkinsfile',
        'libs/public-health/Jenkinsfile',
    ],
    // Jenkins credential ID for the GitHub App. Required, no default; vbu
    // stays org-agnostic so the literal UUID lives next to the org context.
    githubCredentialsId: 'fad62062-b1f4-447b-997f-005d6b1ea41e',
    folderPrefix: 'Public',  // optional, defaults to "Public"
)

The provisioned pipelines land under <folderPrefix>/<repo>/libs/<pkg>/.

Per-package Jenkinsfile

Each libs/<pkg>/Jenkinsfile calls reusable_pipeline() the same way a standalone repo would, with one new argument:

@Library('vivarium_build_utils') _

reusable_pipeline(
    test_types: ['unit', 'integration'],
    deployable: true,
    env_reqs: 'ci_jenkins',  // pyproject.toml extra to install
)

env_reqs selects which [project.optional-dependencies] extra make install pulls in. Omit it (or leave empty) on standalone repos to keep base.mk’s default of dev.

Deployable callers (deployable: true) can also pass github_credentials_id: '<jenkins-credential-id>' to override the git credential used at deploy time for pushing the release tag. When omitted, the deploy stage falls back to the credential configured on the Multibranch Pipeline’s branch source, which is the right default for most repos.

Tag prefix

The TAG_PREFIX environment variable controls both make tag-version and make validate-tag. It must be set consistently in both targets, or validate-tag will silently look at the wrong set of tags.

  • Standalone repos: leave unset. Tags are v<X.Y.Z>.

  • Monorepo libs: set TAG_PREFIX=vivarium-<lib>- (e.g. vivarium-core-). Tags become vivarium-<lib>-v<X.Y.Z>.

Release workflows that invoke make validate-tag or make tag-version should export TAG_PREFIX before running them.

Fetching from internal Artifactory

IHME_PYPI defaults to the internal Artifactory URL and is woven into EXTRA_INDEX_FLAGS for make install. Override it to empty (make install IHME_PYPI=) in environments that can’t reach IHME’s network (e.g. GitHub Actions runners). make deploy-package-artifactory requires a non-empty IHME_PYPI and is Jenkins/internal-only.

Cross-library PRs

A single PR can modify several interdependent monorepo libraries, including bumping one and consuming the new version of another even though the upstream’s dependency on it still resolves against PyPI (where the new version isn’t released yet). make install CHANGED_LIBS="<lib1> <lib2> ..." opts a build into in-tree resolution where any CHANGED_LIBS (libraries whose source changed in the PR) that are also (1) reachable from the package being built and (2) whose pending CHANGELOG.rst version satisfies the dependents’ pins are installed editably from local source (at the pending version) with a single uv invocation. Unchanged dependencies still resolve from PyPI.

CHANGED_LIBS is a no-op when empty, so single-package installs are unaffected.

The GitHub Actions CI and release workflows wire this automatically.

Project links

Data verified by PyPI on Jul 23, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (4.5.1)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for vivarium from gravatar.com vivarium

Credits

Author: The vivarium developers

GitHub Statistics

Data verified by PyPI on Jul 23, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

BSD License (BSD-3-Clause)

Requires

Python >=3.10

Provides Extra

cluster docs interactive test lint dev ci-github ci-jenkins

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

vivarium_build_utils-4.4.2.tar.gz (73.5 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

vivarium_build_utils-4.4.2-py3-none-any.whl (35.7 kB view details)

Uploaded Python 3

File details

Details for the file vivarium_build_utils-4.4.2.tar.gz.

File metadata

  • Download URL: vivarium_build_utils-4.4.2.tar.gz
  • Upload date:
  • Size: 73.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for vivarium_build_utils-4.4.2.tar.gz
Algorithm Hash digest
SHA256 655f330d8472a5384358d18d2e0ac5cfb88d4646d0d9a3dfce06daab0b765a5b
MD5 83d61d528d2600f950ccf62d756242c3
BLAKE2b-256 685fed3d934fe4831946c2b66c02cf4f1e03e06279132bca31ff008c48d27804

See more details on using hashes here.

Provenance

The following attestation bundles were made for vivarium_build_utils-4.4.2.tar.gz:

Publisher: release.yml on ihmeuw/vivarium-suite

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file vivarium_build_utils-4.4.2-py3-none-any.whl.

File metadata

File hashes

Hashes for vivarium_build_utils-4.4.2-py3-none-any.whl
Algorithm Hash digest
SHA256 824a03f768273a26f8b79b42e339a5292f89abbbe477ade28cbdbb411d5602de
MD5 99213576f682a861a42b8f0f4593d6c3
BLAKE2b-256 ba66998d8f9e72c3b2c1b80aea8bd1b8a2093f6d61d19a9fe71508282d0fe64b

See more details on using hashes here.

Provenance

The following attestation bundles were made for vivarium_build_utils-4.4.2-py3-none-any.whl:

Publisher: release.yml on ihmeuw/vivarium-suite

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

4.5.1

2 files

4.5.0

2 files

This release

4.4.2 This release

2 files

4.4.1

2 files

4.4.0

2 files

4.3.0

2 files

4.2.5

2 files

4.2.4

2 files

4.2.3

2 files

4.2.2

2 files

4.2.1

2 files

4.2.0

2 files

4.1.0

2 files

4.0.2

2 files

4.0.1

2 files

4.0.0

2 files

3.3.4

2 files

3.3.3

2 files

3.3.2

2 files

3.3.1

2 files

3.3.0

2 files

3.2.2

2 files

3.2.1

2 files

3.2.0

2 files

3.1.2

2 files

3.1.1

2 files

3.1.0

2 files

3.0.4

2 files

3.0.3

2 files

3.0.2

2 files

3.0.1

2 files

3.0.0

2 files

2.3.8

2 files

2.3.7

2 files

2.3.6

2 files

2.3.5

2 files

2.3.4

2 files

2.3.3

2 files

2.3.2

2 files

2.3.1

2 files

2.3.0

2 files

2.2.4

2 files

2.2.3

2 files

2.2.2

2 files

2.2.1

2 files

2.1.2

2 files

2.1.1

2 files

2.1.0

2 files

2.0.13

2 files

2.0.12

2 files

2.0.11

2 files

2.0.10

2 files

2.0.9

2 files

2.0.8

2 files

2.0.7

2 files

2.0.6

2 files

2.0.5

2 files

2.0.4

2 files

2.0.3

2 files

2.0.2

2 files

2.0.1

2 files

2.0.0

2 files

1.1.2

2 files

1.1.1

2 files

1.1.0

2 files

1.0.0

2 files

0.1.0

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page