# lifelines: survival analysis in Python, from Kaplan-Meier curves to Cox models

> lifelines is a pure Python library for survival analysis, covering Kaplan-Meier estimation, Nelson-Aalen, and regression models such as Cox proportional hazards. It fits teams that have time-to-event data and need censoring handled correctly, not a general-purpose statistics package.

**CamDavidsonPilon/lifelines** — Survival analysis in Python

- Repository: https://github.com/CamDavidsonPilon/lifelines
- Website: lifelines.readthedocs.org
- Stars: 2,613 · Forks: 584
- Language: Python
- License: MIT
- Published: 2026-09-28 · Updated: 2026-09-28 · Language: en
- Canonical page: https://hysenlabs.com/projects/camdavidsonpilon-lifelines

## What lifelines solves, and who it is actually for

Survival analysis answers a question ordinary regression handles badly: why do events occur now rather than later, when some subjects never experience the event at all during observation. The README frames the origin of the field in actuarial and medical work, where the event might be a death or a disease remission, and then widens the scope. SaaS providers measuring subscriber lifetimes, inventory analysts treating a stock-out as a censoring event for true demand, sociologists studying the duration of political parties or marriages, and A/B tests measuring how long different groups take to act are all listed as applications in the README.

The library is for people who already have a duration column and a status column and want the standard estimators without writing maximum likelihood code themselves. That is a narrower audience than a general statistics package serves. If your outcome is a category or a continuous measurement with no censoring, lifelines is the wrong tool, and the repository's own framing makes that clear: the whole design assumes an event time plus an observation window. The topics list on the repository names cox-regression, maximum-likelihood, reliability-analysis and survival-analysis, which is an accurate summary of the surface area.

## How the estimators and regression models are organised

The package is a pure Python implementation, and setup.py declares a single install_requires list read from reqs/base-requirements.txt, so the dependency surface is whatever that file names plus Python itself. The top-level lifelines/ directory holds the implementation, and the repository ships datasets under lifelines/datasets, exposed through package_data. That matters in practice: examples can load a bundled dataset without a separate download step.

On the modelling side, the README describes the library as covering Kaplan Meier, Nelson Aalen and regression. The examples/ directory shows how far the regression side goes. There are notebooks for piecewise exponential models, custom regression models, B-splines, Royston-Parmar splines, and Cox residuals, plus scripts for cure models, mixture cure models, Haft models, copula frailty Weibull models and interval censoring. So the design is not a single Cox implementation with a thin wrapper. It is a set of parametric and semi-parametric models sharing a fitting interface, with maximum likelihood as the common estimation route. The paper/ directory in the repository root suggests the methods were written up formally, which is more than most research-adjacent Python packages offer.

## Installing lifelines and getting to a first fit

The README points to the documentation and tutorials page at lifelines.readthedocs.org for API, syntax and examples, and the PyPI and conda-forge badges indicate the package is distributed through both channels. Python 3.11 is the floor: setup.py sets python_requires to ">=3.11", and the classifiers list 3.11 through 3.14. On an older interpreter pip will refuse the install rather than fail later at import time.

The repository's own development setup shows the install command it expects contributors to use:

```bash
pip install -r reqs/dev-requirements.txt
```

That pulls the development requirements from the file the Makefile references under its init target. The same target then runs pre-commit install, so the repository expects a pre-commit hook in place before you touch the code. For using the library rather than developing it, the README's documentation page is the entry point for API and syntax, and the bundled datasets under lifelines/datasets mean the examples in examples/ can be run without downloading external data. The Makefile also records the test command, py.test lifelines/ -rfs --cov=lifelines, and black at a 120-character line length, which is the formatting the project enforces on itself.

## Where lifelines breaks down or is the wrong choice

The censoring assumption is the sharpest edge. Every estimator here assumes that a censored subject's future is statistically similar to that of subjects still under observation. If people drop out of your study precisely because they are about to churn, or if equipment is removed from a reliability test because it is already degrading, that assumption fails and the curves are biased. No amount of API polish fixes this. It is a property of the data collection, not the library.

The second constraint is the proportional hazards assumption in Cox models. The repository ships a dedicated notebook on checking it, which tells you the maintainers consider it a routine step rather than an edge case. If a covariate's effect changes over time, the hazard ratio reported by the model summary is an average that describes no actual time point. The examples cover alternatives such as piecewise exponential models and spline-based models, so the library gives you somewhere to go, but a default Cox fit will not warn you.

Finally, the Python version floor is a real adoption cost. Requiring 3.11 or newer excludes long-lived environments pinned to older interpreters, and because setup.py declares the constraint, there is no supported path around it short of forking. The package classifier still reads "Development Status :: 4 - Beta" despite the release history, which is worth knowing if your procurement process keys off that field.

## How lifelines compares to R's survival package

The most common alternative for this work is R's survival package, which has been the reference implementation in the field for decades and is what most published methodology is validated against. The difference in approach is not just language. In R, survival analysis sits inside a formula-and-data-frame idiom shared with lm and glm, and the ecosystem around it (survminer for plots, flexsurv for parametric models) is mature and widely cited in medical literature.

lifelines takes the opposite bet: it is a pure Python implementation, so it fits into a pipeline where the data already lives in pandas and the results feed a Python service. The cost is that you are trusting a reimplementation rather than the canonical one. For standard Kaplan-Meier and Cox work the two should agree closely, and the repository's paper/ directory and the CITATION.cff file suggest the methods are documented rather than reverse-engineered. For less common models, particularly the frailty and cure models shown in examples/, you should check whether the R equivalent has a validation history you need for publication. If your output goes into a regulatory submission or a clinical paper, that question matters more than the API.

## Maintenance, upgrades and the MIT licence

The repository is not archived, and the last push was on 2026-03-07. Releases v0.30.1, v0.30.2 and v0.30.3 all landed between 2026-02-04 and 2026-03-05, so the release cadence at that point was weeks, not years. The CHANGELOG.md at the repository root is where upgrade notes live, and it is the file to read before bumping a pinned version, since estimator APIs in a statistics library can change in ways that alter numeric output rather than raising an error.

The licence is MIT, declared both in setup.py and in the LICENSE file, and the classifier confirms OSI approval. That is permissive: you can use it commercially and modify it. It also means there is no warranty and no support obligation on the maintainer, which for a library that produces numbers you may act on is worth stating plainly. The README directs questions to the GitHub Discussions room, and notes that some users post at stats.stackexchange.com, so community help exists but is not a support contract. The Makefile shows the development workflow: pip install -r reqs/dev-requirements.txt, then pre-commit install, with py.test lifelines/ for the test suite and black at a 120-character line length. If you vendor a fork, that is the loop you inherit.

## Conclusion

Adopt lifelines when your data has a time-to-event column plus a censoring indicator and you need Kaplan-Meier curves, Nelson-Aalen estimates or a Cox proportional hazards model without leaving Python. Skip it if you need a general regression toolkit, deep learning survival models, or a package that still supports Python 3.10 and older. Before committing, verify that your installed Python is 3.11 or newer, that your event column distinguishes observed events from censored observations, and that the proportional hazards assumption holds for your covariates, which the repository's examples/Proportional hazard assumption.ipynb notebook walks through.

## FAQ

### How do I install lifelines?

It is distributed on PyPI and conda-forge, and setup.py declares python_requires as >=3.11. Older interpreters will be rejected at install time rather than failing later.

### How do I install lifelines in a Jupyter notebook?

The repository does not document a notebook-specific install path. The install is the same one used for any Python environment, and the bundled datasets under lifelines/datasets let you load example data without a separate download.

### What Python version does lifelines require?

setup.py sets python_requires to ">=3.11", and the classifiers list Python 3.11 through 3.14. There is no supported path for older interpreters.

### What models does lifelines provide beyond Kaplan-Meier?

The README names Kaplan Meier, Nelson Aalen and regression, and the examples directory adds piecewise exponential models, B-splines, Royston-Parmar splines, cure models, Haft models and copula frailty Weibull models. Maximum likelihood is the common estimation route across them.

### What licence is lifelines released under?

MIT, declared in setup.py and in the LICENSE file, with the OSI-approved classifier. That permits commercial use and modification, with no warranty from the maintainer.

## Sources

- [CamDavidsonPilon/lifelines on GitHub](https://github.com/CamDavidsonPilon/lifelines)
- [Issues](https://github.com/CamDavidsonPilon/lifelines/issues)
- [License: MIT](https://github.com/CamDavidsonPilon/lifelines/blob/master/LICENSE)
- [README](https://github.com/CamDavidsonPilon/lifelines/blob/master/README.md)
- [Releases](https://github.com/CamDavidsonPilon/lifelines/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/camdavidsonpilon-lifelines