Jython Developer’s Guide

This guide is a comprehensive resource for contributing to Jython – for both new and experienced contributors. It has been adapted from the CPython Developer’s Guide and the reader should bear in mind that:

  • The CPython process is PR-based on GitHub and this guide anticipates our adoption of that for Jython.
  • The existing Jython process uses Mercurial so the guide describes that too.
  • Statements about “Python” should apply to both CPython and Jython.
  • The adaptation is imperfect: parts of the guide will say (or mean) CPython.

This guide is maintained by the same community that maintains CPython and Jython. We welcome your contributions to either implementation of Python!

Quick Reference


  1. Get the source code:

    hg clone http://hg.python.org/jython
  2. Build Jython:

  3. Run the tests:

    ant regrtest
  4. Make the patch.

  5. Submit it to the Jython issue tracker.


Here are the basic steps needed to get set up and contribute a patch. This is meant as a checklist, once you know the basics. For complete instructions please see the setup guide.

  1. Install and set up Git and other dependencies (see the Get Setup page for detailed information).

  2. Fork the Jython repository to your GitHub account and get the source code using:

    git clone https://github.com/<your_username>/jython
  3. Build Jython using:


    issued in the base check-out directory. The built application will be in subdirectory dist. See also more detailed instructions, and how to build dependencies.

  4. Run the tests:

    dist/bin/jython -m test -e

    (for Jython 3). With Jython 2.7, replace test with test.regrtest.

  5. Create a new branch where your work for the issue will go, e.g.:

    git checkout -b fix-issue-12345 master

    If an issue does not already exist, please create it. Trivial issues (e.g. typo fixes) do not require any issue to be created.

  6. Once you fixed the issue, run the tests, and if everything is ok, commit.

  7. Push the branch on your fork on GitHub and create a pull request. Include the issue number using bpo-NNNN in the pull request description. For example:

    bpo-12345: Fix some bug in spam module


bpo stands for bugs.python.org and these flags are used by CPython’s GitHub tools. For Jython we need our own naming convention, and to re-use the CPython tools. It is also worth considering whether we move away from bugs.jython.org to GitHub issues, and how we do that.


First time contributors will need to sign the Contributor Licensing Agreement (CLA) as described in the Licensing section of this guide.

Status of Jython branches


Maybe how it should look in a process based on GitHub, and for Jython 3. Not how it is.

Branch Schedule Status First release End-of-life Comment
master   features     The default branch is currently the future Jython 3.5.
2.7   bugfix     The support has been extended to 2020 (1). Most recent binary release: Jython 2.7.1
2.5   end-of-life     Final release: Jython 2.5.3

(1) The exact date of Python 2.7 end-of-life has not been decided yet. It will be decided by Python 2.7 release manager, Benjamin Peterson, who will update the PEP 373. Read also the [Python-Dev] Exact date of Python 2 EOL? thread on python-dev (March 2017).


features:new features are only added to the master branch, this branch accepts any kind of change.
bugfix:bugfixes and security fixes are accepted, new binaries are still released.
security:only security fixes are accepted and no more binaries are released, but new source-only versions can be released
end-of-life:release cycle is frozen; no further changes can be pushed to it.

Dates in italic are scheduled and can be adjusted.

By default, the end-of-life is scheduled 5 years after the first release. It can be adjusted by the release manager of each branch. Versions older than 2.7 have reached end-of-life. The Jython project follows the Python Software Foundation in the naming of versions of the language (e.g. Jython 2.7 implements Python 2.7), and whether an implementation of that version has reached reached end-of-life.

See also Security branches.

Each release of Python is tagged in the source repo with a tag of the form vX.Y.ZTN, where X is the major version, Y is the minor version, Z is the micro version, T is the release level (a for alpha releases, b for beta, rc release candidate, and null for final releases), and N is the release serial number. Some examples of release tags: v3.7.0a1, v3.6.3, v2.7.14rc1.

The code base for a release cycle which has reached end-of-life status is frozen and no longer has a branch in the repo. The final state of the end-of-lifed branch is recorded as a tag with the same name as the former branch, e.g. 3.3 or 2.6. For reference, here are the most recently end-of-lifed release cycles:

Tag Schedule Status First release End-of-life Comment
3.3 PEP 398 end-of-life 2012-09-29 2017-09-29 Final release: Python 3.3.7
3.2 PEP 392 end-of-life 2011-02-20 2016-02-20 Final release: Python 3.2.6
3.1 PEP 375 end-of-life 2009-06-27 2012-04-11 Final release: Python 3.1.5
3.0 PEP 361 end-of-life 2008-12-03 2009-01-13 Final release: Python 3.0.1
2.6 PEP 361 end-of-life 2008-10-01 2013-10-29 Final release: Python 2.6.9


We encourage everyone to contribute to Python and that’s why we have put up this developer’s guide. If you still have questions after reviewing the material in this guide, then the Python Mentors group is available to help guide new contributors through the process.

A number of individuals from the Python community have contributed to a series of excellent guides at Open Source Guides.

Core developers and contributors alike will find the following guides useful:

Guide for contributing to Jython:

It is recommended that the above documents be read in the order listed. You can stop where you feel comfortable and begin contributing immediately without reading and understanding these documents all at once. If you do choose to skip around within the documentation, be aware that it is written assuming preceding documentation has been read so you may find it necessary to backtrack to fill in missing concepts and terminology.

Proposing changes to Python itself

Improving Python’s code, documentation and tests are ongoing tasks that are never going to be “finished”, as Python operates as part of an ever-evolving system of technology. An even more challenging ongoing task than these necessary maintenance activities is finding ways to make Python, in the form of the standard library and the language definition, an even better tool in a developer’s toolkit.

While these kinds of change are much rarer than those described above, they do happen and that process is also described as part of this guide:

Other Interpreter Implementations

This guide is specifically for contributing to Jython, that is, Python on the JVM. (While most of the standard library is written in Python, the interpreter core is written in Java and integrates most easily with the Java SE and EE ecosystems).

There are other Python implementations, each with a different focus. Like Jython, they always have more things they would like to do than they have developers to work on them. Some major example that may be of interest are:

  • CPython: The reference implementation of Python implemented in C, and the main focus of language development.
  • PyPy: A Python interpreter focused on high speed (JIT-compiled) operation on major platforms
  • IronPython: A Python interpreter focused on good integration with the Common Language Runtime (CLR) provided by .NET and Mono
  • Stackless: A Python interpreter focused on providing lightweight microthreads while remaining largely compatible with CPython specific extension modules

Key Resources

Additional Resources

Code of Conduct

Please note that all interactions on Python Software Foundation-supported infrastructure is covered by the PSF Code of Conduct, which includes all infrastructure used in the development of Python itself (e.g. mailing lists, issue trackers, GitHub, etc.). In general this means everyone is expected to be open, considerate, and respectful of others no matter what their position is within the project.

Full Table of Contents