citeproc-py

citeproc-py is a CSL processor for Python. It aims to implement the CSL 1.0.2 specification. citeproc-py can output styled citations and bibliographies in a number of different output formats. Currently supported are plain text, reStructuredText and HTML. Other formats can be added easily.

citeproc-py uses semantic versioning. Currently, its major version number is still at 0, meaning the API is not yet stable. However, you should not expect to see any major API changes soon.

Requirements

citeproc-py supports Python 3.9 and up. It depends on lxml for parsing and navigating the CSL style and locale files.

Installation

The recommended way of installing citeproc-py is by using pip:

   pip install citeproc-py

If lxml isn't installed, pip will try to install it for you.

If you insist, you can manually install citeproc-py from distribution packages hosted at PyPI. Please ignore the release archives offered by GitHub.

Getting Started

To get started with citeproc-py, take a look at the examples under examples/. Two examples are provided, one parsing references from a JSON representation of references as supported by citeproc-js, another parsing the references from a BibTeX file. Both show and explain how to cite references and render the bibliography.

CSL Compatibility

Currently, citeproc-py passes about 60% of the tests in the citeproc-test suite. A non-exhaustive list of functionality that is missing includes:

• disambiguation/year-suffix
• et-al-subsequent-min/et-al-subsequent-use-first
• collapsing
• punctuation-in-quote
• display

Also, some citeproc-js functionality that is not part of the CSL spec is not (yet) supported:

• raw dates
• static-ordering
• literal names

Contributing

citeproc-py is 100% volunteer maintained, and new contributions are always welcome. If you would like to contribute, please follow the guidelines in the CONTRIBUTING.md file.

Local Install and Running the Tests

First clone the citeproc-py repository and install the submodules with

git submodule update --init

If you want git to fully ignore the submodules, you can type

git update-index --assume-unchanged citeproc/data/schema
git update-index --assume-unchanged citeproc/data/locales

Then install with

pip install --editable .[tests]

You can run all the tests using tox:

tox run -e py314

Or you can manually run citeproc-test tests using

python tests/citeproc-test.py

The first time you run the script it will clone the citeproc-test suite repository into the tests directory and checkout the last tested version. By default failed tests are automatically added into the failing_tests.txt file and aren't shown when running the test suite again.

citeproc-py uses ruff for linting. You can run it directly using ruff check. Any test failures or linting errors will show up on the CI and will need to be fixed before a Pull Request can be merged.

v0.12.0 (Fri Oct 30 2026)

🚀 Enhancement

• docs: mention ruff in README and CONTRIBUTING #212 (@alexfikl)
• test: add ruff to ci #212 (@alexfikl)
• fix: all ruff B errors #212 (@alexfikl)
• fix: all ruff Q errors #212 (@alexfikl)
• fix: all ruff I errors #212 (@alexfikl)
• fix: all ruff W errors #212 (@alexfikl)
• fix: all ruff F errors #212 (@alexfikl)
• fix: all ruff E errors #212 (@alexfikl)
• fix: all ruff UP errors #212 (@alexfikl)
• chore: add ruff config #212 (@alexfikl)

Authors: 1

• Alex Fikl (@alexfikl)

---

v0.11.1 (Tue Sep 01 2026)

🐛 Bug Fix

• Contributing: update contributing guidelines #214 (@tmorrell)
• coverage: ignore _version.py #214 (@tmorrell)
• tests: recommend tox and modernize coveralls setup #214 (@tmorrell)

🏠 Internal

• tests: remove global, ancient python code, and deprecated load_module #213 (@tmorrell)

Authors: 1

• Tom Morrell (@tmorrell)

---

v0.11.0 (Thu Aug 20 2026)

🚀 Enhancement

• test: refresh citeproc seam expectations #208 (@tomatotomata)
• fix: normalize punctuation at formatter seams #208 (@tomatotomata)
• Update compatability description #208 (@tmorrell)
• Normalize whitespace and duplicate punctuation at string seams #208 (@tmorrell)

Authors: 2

• Tom Morrell (@tmorrell)
• tomatotomata (@tomatotomata)

---

v0.10.7 (Mon Aug 10 2026)

🐛 Bug Fix

• fix default delimiter #201 (@tmorrell)

Authors: 1

• Tom Morrell (@tmorrell)

---

v0.10.6 (Mon Aug 10 2026)

🐛 Bug Fix

• Count citation-number as a variable call in cs:group #206 (@eseifert)

Authors: 1

• Erich Seifert (@eseifert)

---

v0.10.5 (Mon Aug 10 2026)

🐛 Bug Fix

• fix(model): add defensive check in get_locale_option() for Locale roots #209 (@kyodai0000)

Authors: 1

• Ondřej Ruml (@kyodai0000)

---

v0.10.4 (Wed Aug 05 2026)

🐛 Bug Fix

• setup.py: Prune imports #191 (@hseg)
• Remove unneeded nonuniversal wheel declaration #191 (@hseg)
• Fix project URL #191 (@hseg)
• Specify license file #191 (@hseg)
• Add missing build dep: lxml #191 (@hseg)
• Use entry points for running scripts #191 (@hseg)
• Use setuptools' builtin multifile longdesc support #191 (@hseg)
• Rely on setuptools' automatic package discovery #191 (@hseg)
• Migrate versioneer to pyproject.toml #191 (@hseg)
• Migrate simple metadata to pyproject.toml #191 (@hseg)

Authors: 1

• @hseg

---

v0.10.3 (Fri Jul 24 2026)

🐛 Bug Fix

• swap csl 1.0.1 harvard1 for harvard-cite-them-right #197 (@tmorrell)
• tests: add python 3.14 #199 (@tmorrell)

🔩 Dependency Updates

• build(deps): bump actions/setup-python from 6 to 7 #200 (@dependabot[bot])

Authors: 2

• @dependabot[bot]
• Tom Morrell (@tmorrell)

---

v0.10.2 (Tue Jul 21 2026)

🐛 Bug Fix

• Additional chicago style page range formats in csl 1.0.2 #198 (@tmorrell)

Authors: 1

• Tom Morrell (@tmorrell)

---

v0.10.1 (Wed Jul 08 2026)

🐛 Bug Fix

• Update GitHub Actions for token and Python version #196 (@tmorrell)
• Better handle decimals in multiple number regex #195 (@tmorrell)
• fix spacing changes in csl 1.0.2 #195 (@tmorrell)

Authors: 1

• Tom Morrell (@tmorrell)

---

v0.10.0 (Tue Jul 07 2026)

🚀 Enhancement

• fix: preserve text case for non-english title case #192 (@mairasalazar)
• Upgrade to csl 1.0.2 #192 (@mairasalazar)

🔩 Dependency Updates

• Bump actions/checkout from 6 to 7 #193 (@dependabot[bot])

Authors: 2

• @dependabot[bot]
• Maira Salazar (@mairasalazar)

---

v0.9.3 (Thu Apr 30 2026)

🐛 Bug Fix

• fix: Et_Al looked up literal term name 'variable' instead of the local variable #190 (@Jasaj4)

🔩 Dependency Updates

• Bump actions/checkout from 4 to 6 #187 (@dependabot[bot])
• Bump actions/setup-python from 5 to 6 #186 (@dependabot[bot])

Authors: 2

• @dependabot[bot]
• @Jasaj4

---

v0.9.2 (Tue Apr 21 2026)

🐛 Bug Fix

• setup: add citeproc-py-styles to tests #189 (@tmorrell)

Authors: 1

• Tom Morrell (@tmorrell)

---

v0.9.1 (Mon Apr 20 2026)

🐛 Bug Fix

• Add Dependabot configuration for GitHub Actions #185 (@tmorrell)
• tests: drop python 3.9 #179 (@tmorrell)
• Fix ordinal suffixes when style has embedded locale without ordinal terms #184 (@Copilot)

Authors: 2

• @Copilot
• Tom Morrell (@tmorrell)

---

v0.9.0 (Mon Aug 25 2025)

🚀 Enhancement

• Feature/flexible style loading #180 (@yarikoptic)

Authors: 1

• Yaroslav Halchenko (@yarikoptic)

---

v0.8.3 (Mon Aug 18 2025)

🐛 Bug Fix

• setup: match license label with actual text #175 (@tmorrell)
• Fix Non-existent Terms #156 (@JVickery-TBS)

🏠 Internal

• Remove hardcoded option for auto to onlyPublishWithReleaseLabel #178 (@yarikoptic)
• release action: missing semicolon #177 (@tmorrell)
• release action: missing quotes #176 (@tmorrell)
• coveralls: try to reenable #163 (@tmorrell)

📝 Documentation

• Fix some formatting issues in README #164 (@alexfikl)

Authors: 4

• Alex Fikl (@alexfikl)
• Jesse Vickery (@JVickery-TBS)
• Tom Morrell (@tmorrell)
• Yaroslav Halchenko (@yarikoptic)

---

v0.8.2 (Wed Mar 12 2025)

🏠 Internal

• Explicitly specify utf-8 encoding while reading top level .md files for description #162 (@yarikoptic)
• Instruct that long description is in markdown and not ReST #160 (@yarikoptic)

Authors: 1

• Yaroslav Halchenko (@yarikoptic)

---

v0.8.1 (Wed Mar 12 2025)

🏠 Internal

• release: checkout with submodules #159 (@yarikoptic)

Authors: 1

• Yaroslav Halchenko (@yarikoptic)

---

v0.8.0 (Wed Mar 12 2025)

🚀 Enhancement

• release: use GitHUb App token for checkout and push #158 (@tmorrell)

⚠️ Pushed to master

• Rename CHANGES to CHANGELOG (@yarikoptic)

🏠 Internal

• release: switch to using GitHub App to overcome branch protection #157 (@tmorrell)
• Set up auto to automate releases #153 (@jwodder @yarikoptic)

📝 Documentation

• Convert CHANGES.rst, CONTRIBUTING.rst, and README.md to markdown #154 (@tmorrell)

Authors: 3

• John T. Wodder II (@jwodder)
• Tom Morrell (@tmorrell)
• Yaroslav Halchenko (@yarikoptic)

---

Release 0.7.0 (2025-02-19)

Just to get a release out after long period.

Bug fixes

• Better handling of ordinals
• Fix locator conditions (resolves #142)
• Make family name optional
• Allow date parts to not be integers
• Support space macros
• Fix multiple capitals
• Fix parsing BibTex integer values

Other changes:

• Removed support for Python 3.6, 3.7, 3.8 and added for 3.10 - 3.13
• Switch versioning to versioneer

Release 0.6.0 (2021-05-27)

Bug fixes

• Various issues on Windows: testing, explicit utf-8 encoding
• Strings with unescaped \ declared r"aw"

Other changes:

• Removed support for Python 2.7, 3.5 and added for 3.9
• Travis CI is removed in favor of GitHub actions testing across all 3 major OSes (MacOS, Windows, GNU/Linux Ubuntu)
• CSL test-suite progressed from 5779a8c to c3db429

Release 0.5.1 (2020-03-06)

Bug fixed:

• avoid rnc2rng 2.6.2 which breaks installation of citeproc-py

Release 0.5.0 (2020-02-09)

Enhancements:

• handle commas and ampersands in a functional style
• Number: handle commas and ampersands
• added symbol for textquotesingle
• specify fallback locales for fr-CA and es-CL
• improved page number and ranges parsing

Bug fixed:

• don't fail on empty page ranges (#90) (bbm)
• detect end of file while parsing incorrect bib (#59) (John Vandenberg)

Other changes:

• Removed 3.2-3.4 and added 3.7, 3.8 to supported Pythons
• Refactored locales handling

Release 0.4.0 (2017-06-23)

New features:

• allow specifying the encoding of a BibTeX database file (#20 and #25)
• BibTeX 'month' field: support integers and " " values
• BibTeX 'pages' field: support "10", "10+", "10-12" and "10--12" formats
• BibTeX entry types: map the non-standard 'thesis' and 'report' entries
• update the CSL schema to version 1.0.1 (#5)
• update the CSL locales to commit 49bf3fc0

Bug fixed:

• avoid crash when there is nothing to affix (David Lesieur)
• fix BibTeX month to CSL month mapping (#24)
• strip leading/trailing whitespace from BibTeX values (#37)

Release 0.3.0 (2014-11-07)

Major improvements to the BibTeX parser:

• split names into parts and assign them to the equivalent CSL name parts
• fixed handling of accent macros and escaped characters
• more compatible (La)TeX macro handling in general (but still basic)
• handle standard Computer Modern ligatures such as --, ---, and <<
• added unit tests for the BibTeX and LaTeX parsers

Other changes:

• disable RelaxNG validation of CSL styles by default (API change)

Release 0.2.0 (2014-10-25)

• bad cite callback function can determine how a bad cite is displayed (hetsch)
• added option to disable RelaxNG validation (Jasper Op de Coul)
• distutils was replaced with setuptools (Joshua Carp)
• bug fixes (Yaroslav Halchenko, David Lesieur)
• CitationStylesBibliography.bibliography() now returns the list of entries