Skip to main content

Tests Codecov PyPI Version Python Version Docs

pyworkforce

Practical workforce planning in Python: queue staffing, shift scheduling, rostering, and breaks.

pyworkforce helps teams turn variable demand into staffing decisions with a friendly, scikit-learn-like API. It combines Erlang queueing models and OR-Tools constraint programming so workforce analysts, data scientists, operations researchers, and Python developers can move from forecast volumes to workable staffing plans without building every solver from scratch.

It is useful for contact centers and call centers, but the same patterns apply to healthcare staffing, retail operations, logistics, support teams, service desks, and field operations.

Docs: pyworkforce.rodrigo-arenas.com
Package: PyPI
Examples: examples/

Why pyworkforce?

  • More practical than spreadsheets: reusable models, scenario sweeps, tested calculations, and outputs that fit naturally into pandas workflows.
  • Faster than custom scripts: common workforce planning steps are packaged behind consistent constructors, solve() methods, validation, and clear result dictionaries.
  • Lighter than enterprise WFM tools: use it inside notebooks, pipelines, internal apps, simulations, or decision-support workflows without adopting a full platform.
  • Built on proven methods: Erlang C, Erlang A, and Erlang B for queue staffing; OR-Tools CP-SAT for scheduling, rostering, and break placement.
  • Designed for adoption: small examples, copy-paste tutorials, and APIs that feel familiar to Python users.

Installation

pip install pyworkforce

pyworkforce supports Python 3.12, 3.13, and 3.14.

Install the plotting extra to explore coverage and Erlang C staffing curves with Matplotlib:

pip install "pyworkforce[plot]"

The schedule stress-test tutorial shows how to set staffing limits by shift and compare a solved plan against multiple demand forecasts. The Erlang C staffing curve tutorial shows how to choose a headcount against service and occupancy targets.

Planning pipeline

Forecast demand -> Queue staffing -> Multi-skill staffing -> Shift scheduling -> Rostering -> Break scheduling

Planning pipeline

Step Module Typical question
Queue staffing pyworkforce.queuing How many agents or channels do we need for a service target?
Multi-skill staffing pyworkforce.staffing What skill-profile mix covers all queues at minimum cost?
Shift scheduling pyworkforce.scheduling How many people should work each shift?
Rostering pyworkforce.rostering Which named people work on which days and shifts?
Break scheduling pyworkforce.breaks When can breaks happen without dropping below coverage?

What can I do in 5 minutes?

Size a contact-center queue with Erlang C

from pyworkforce.queuing import ErlangC

erlang = ErlangC(
    transactions=100,  # calls in the interval
    aht=3,             # average handle time, minutes
    asa=20 / 60,       # answer-time target, minutes
    interval=30,       # interval length, minutes
    shrinkage=0.30,
)

print(erlang.required_positions(service_level=0.80, max_occupancy=0.85))
{'raw_positions': 14,
 'positions': 20,
 'service_level': 0.8883500191794669,
 'occupancy': 0.7142857142857143,
 'waiting_probability': 0.1741319335950498}

raw_positions is productive staffing. positions adds shrinkage for breaks, training, meetings, and other unavailable time.

Compare staffing scenarios

from pyworkforce.queuing import MultiErlangC
from pyworkforce.utils import results_to_dataframe

param_grid = {
    "transactions": [80, 100, 120],
    "aht": [3],
    "asa": [20 / 60],
    "interval": [30],
    "shrinkage": [0.20, 0.30],
}

multi = MultiErlangC(param_grid=param_grid, n_jobs=-1)
results = multi.required_positions({"service_level": [0.80], "max_occupancy": [0.85]})
df = results_to_dataframe(results, multi.required_positions_params)
print(df[["transactions", "shrinkage", "positions", "service_level"]])

Use this pattern to compare service levels, shrinkage assumptions, average handle time, patience, or arrival forecasts.

Build shift coverage from clock hours

from pyworkforce.shifts import shift_coverage_from_hours

shifts_coverage = shift_coverage_from_hours(
    {
        "Morning": (6, 14),
        "Afternoon": (14, 22),
        "Night": (22, 6),  # wraps past midnight
    },
    num_periods=24,
)

The result feeds the scheduling solvers directly, avoiding hand-written 0/1 coverage arrays.

Main capabilities

Capability Use it when Start here
Erlang C staffing Callers wait and abandonment is ignored or negligible Erlang C guide
Erlang A staffing Callers may abandon before being answered Erlang A guide
Erlang B channel sizing Blocked calls are lost because there is no queue Erlang B guide
Multi-skill staffing Agents can cover different skill combinations Staffing guide
Shift scheduling You need shift counts from hourly demand Scheduling guide
Employee rostering You need named assignments with rules and preferences Rostering guide
Break scheduling You need meal/rest breaks while maintaining coverage Break guide

Project status

pyworkforce is beta-stage open source software. The core models are tested and usable for real planning experiments, but workforce policies vary by operation, country, and labor agreement. Validate assumptions, units, and constraints against your own environment before using results operationally.

Documentation

Contributing

Contributions are welcome: examples, documentation, validation improvements, benchmarks, visualization helpers, additional workforce constraints, and bug reports all help. See CONTRIBUTING.md for local setup, tests, docs, and roadmap ideas.

License

pyworkforce is released under the MIT License.

Metadata

Release files for pyworkforce 0.6.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pyworkforce 0.6.0
File Size Uploaded Provenance Actions
pyworkforce-0.6.0.tar.gz 57.7 kB With provenance Details for pyworkforce-0.6.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pyworkforce 0.6.0
File Interpreter ABI Platform Actions
pyworkforce-0.6.0-py3-none-any.whl Python 3 none any Details for pyworkforce-0.6.0-py3-none-any.whl

Total release size: 128.5 kB

Release files / pyworkforce-0.6.0.tar.gz

Download URL pyworkforce-0.6.0.tar.gz
Size 57.7 kB
Tags Source
SHA-256 checksum
How to use checksums
dd44f04640761d40a5d445d359c8d5c27b33d0a3e37ac1cb305cfd45f6934151
BLAKE2b-256 checksum
How to use checksums
0799e78f495aa6e6ac838f647b1749c0db273ee150fe5fe0b7c4ccb9fd85ee9b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Release files / pyworkforce-0.6.0-py3-none-any.whl

Download URL pyworkforce-0.6.0-py3-none-any.whl
Size 70.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
0c42ee41708898f856058f738da1baabeedfea90f651054c8496fb300c41a9f4
BLAKE2b-256 checksum
How to use checksums
6f41c529ff2f5f04b77dda6c8abec192c61806695a9d2d6a240b2b6546444e22
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Security for pyworkforce 0.6.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for pyworkforce-0.6.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page