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
| 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.