/!\ This page is primarily intended for Mercurial's developers.

Python 3

This is a status page for keeping track of what needs to be done to make progress on Mercurial on Python 3.

1. Status

Mercurial 5.0 is the first release that officially has beta support for Python 3. Supported Python 3 versions are 3.5, 3.6, and 3.7. Python 3.8 mostly works, but there are a few known incompatibilities. Mercurial with Python 3 on Windows is not yet widely tested and there are more known issues on Windows compared to Linux, macOS, and other UNIX-like platforms.

It is the project policy for Mercurial and its core extensions to be compatible with Python 3. Over 99% of tests pass with Python 3 and test regressions are treated seriously.

Many 3rd party extensions have not yet been ported to work with Python 3.

2. Using

Mercurial's setup.py file refuses to run with Python 3 by default. This means that pip install Mercurial or python setup.py install will not work with Python 3 by default.

Setting the HGPYTHON3 environment variable will suppress this error and allow execution with Python 3. e.g. HGPYTHON3=1 pip3.7 install Mercurial or HGPYTHON3=1 python3.7 setup.py install.

No run-time environment variable or config option is required to use Python 3 with Mercurial: only the installation step / setup.py requires special action to override the Python version check.

3. Things need to be investigated

4. Beta bugs

Following are things which don't work right now:

If you find anything apart from this not working, definitely go ahead and edit this page and we will fix it.

5. Porting Extensions to Python 3

Nearly every extension will need to be ported to be compatible with Python 3. This is because of fundamental differences between Python 2 and Python 3.

The source code for Mercurial extensions will need to be Python 3 native and will need to be compatible with Mercurial's APIs. In many cases, existing source code will compile on Python 3 but will fail at run-time. Sources of run-time errors include:

Do an Internet search for Python 3 porting to find well-written and comprehensive guides on generically porting code to Python 3.

Extension authors may find the mercurial.pycompat module useful. This modules contains abstractions and utilities for bridging the differences between Python 2 and 3. It is conceptually similar to the six Python module.

As of at least the Mercurial 5.0 release, Mercurial uses a custom module importer on Python 3 which rewrites source code dynamically as part of importing modules. This module importer is only active for the mercurial, hgext, and hgext3rd packages. Extension loading does not use this custom importer. This means that Mercurial's own source code and extensions are not yet native Python 3 source code. So if you look at Mercurial's source code for ideas on how to do something in an extension, behavior in the extension may differ from Mercurial itself due to the presence of this custom module importer. For reference, in the 5.0 release, the custom module importer performs the following actions:

The source rewriting module importer is intended to be a stop-gap to make porting Mercurial to Python 3 simpler and will be removed in a future release. This is why extensions do not use it.

If you need help or guidance on porting extensions, you can message on IRC or the development MailingList. We will be happy to help you.


Python3 (last edited 2019-04-21 16:08:05 by GregorySzorc)