future is the missing compatibility layer between Python 2 and Python 3. It allows you to use a single, clean Python 3.x-compatible codebase to support both Python 2 and Python 3 with minimal overhead. It provides `future` and `past` packages with backports and forward ports of features from Python 3 and 2, and includes `futurize` and `pasteurize` scripts for automated code conversion. The latest version is 1.0.0, and while feature development is complete, it supports Python 3.12.
Install & Compatibility
Where this runs
tested against v1.0.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.10
8/10 runs
8/10 runs
py 3.11
8/10 runs
8/10 runs
py 3.12
8/10 runs
8/10 runs
py 3.13
8/10 runs
8/10 runs
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Builtins
✓ from builtins import (bytes, dict, int, list, object, range, str,
ascii, chr, hex, input, next, oct, open, pow,
round, super, filter, map, zip)
✗ from future.builtins import *
While `future.builtins` exists, the recommended pattern for Python 2/3 compatibility is `from builtins import ...` as it directly maps to Python 3 builtins on Py2 and has no effect on Py3. The wildcard `*` is shown in some examples for brevity but explicit imports are generally preferred.
StandardLibraryAliases
✓ from future.standard_library import install_aliases
install_aliases()
✗ import urllib.parse # Directly on Py2 without aliases
This function makes Python 3-style standard library imports (e.g., `urllib.parse`, `queue`) available on Python 2 by modifying `sys.modules` and other mechanisms.
__future__ imports
✓ from __future__ import (absolute_import, division, print_function, unicode_literals)
These are built-in Python future statements crucial for enabling Python 3 behavior in Python 2. `future`'s tools and runtime patches complement these.
past.builtins
✓ from past.builtins import basestring, unicode
Provides Python 2-specific builtins (like `basestring` or `unicode` type) on Python 3 for modules that explicitly need them, typically during module-by-module migration.
To write new code compatible with both Python 2 (2.6+) and Python 3 (3.3+), start each module with the essential `__future__` imports and `from builtins import *`. Then call `install_aliases()` to ensure standard library modules are correctly mapped. This allows writing predominantly Python 3-style code that runs on both versions.
from __future__ import (absolute_import, division, print_function, unicode_literals)
from builtins import *
from future.standard_library import install_aliases
install_aliases()
# Now write Python 3 code that runs on both Py2 and Py3
print("Hello, world!")
def divide(a, b):
return a / b # Will use float division even on Python 2
my_dict = {'a': 1, 'b': 2}
print(list(my_dict.keys())) # dict.keys() returns a view (iterable) on Py2 with future installed
# Example of Python 3 library name working on Py2
import urllib.request
print(urllib.request.urlopen('http://example.com').getcode())
futurize --version
Debug
Known issues
breakingPython 2 reached its end-of-life in 2020. While `python-future` facilitates compatibility, relying on it for actively maintained Python 2 codebases is increasingly risky due to lack of Python 2 security updates and ecosystem support.fixPrioritize full migration to Python 3. `python-future` should be seen as a stepping stone or a compatibility layer for transitioning legacy code, not a long-term solution for Python 2 development.
affects: <1.0.0 (and general Python 2 usage)
gotchaThe `python-future` project is declared 'done' and is not recommended for new Python 3 projects. While it receives critical compatibility updates (e.g., Python 3.12 support), its primary purpose as a Python 2/3 compatibility layer means new feature development is complete. It should not be adopted as a dependency for greenfield Python 3 development.fixFor new Python 3 projects, write idiomatic Python 3 code directly. If compatibility with multiple Python 3 versions is needed, leverage `__future__` imports (native to Python) and `six` if strictly necessary for very old Python 3 versions, but prefer modern Python features.
affects: All versions, especially 1.0.0+
gotchaThe `install_aliases()` function globally modifies `sys.modules` on Python 2 to map Python 3 standard library names. This can lead to unexpected behavior or conflicts if other libraries or custom import hooks make different assumptions about the module layout.fixUse `install_aliases()` early in your application's startup. Be aware of potential conflicts, especially when mixing with other compatibility layers or dynamically loading modules. Consider explicit `future.moves` imports for specific items to limit global impact if issues arise.
affects: All versions on Python 2
deprecatedThe `past.translation` module, which offers experimental automatic translation of Python 2 modules to Python 3 upon import, is in 'alpha' status and may be unstable or imperfect. Relying on it for critical functionality is not recommended.fixPrefer using `futurize` (for Py2 to Py2/3) or `pasteurize` (for Py3 to Py2/3) scripts for static code conversion. If `past.translation` is used, ensure thorough testing and be prepared for potential runtime issues.
affects: All versions
gotchaHTTPS support with the `http`-based backports within `future` is limited on Python 2.x due to significant changes in SSL support in Python 3.x. Direct `http`-based backports might fail for HTTPS connections.fixFor HTTPS support on Python 2, especially within `urllib`, the documentation recommends using `from future.moves.urllib.request import urlopen` or using a dedicated HTTP library like `requests` that handles SSL/TLS more robustly.
affects: All versions on Python 2.x
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'future'
The 'future' library is not installed in the Python environment where the code is being executed.
ImportError: No module named builtins
This error typically occurs in Python 2 when `from builtins import *` is used, but the 'future' library, which backports Python 3 builtins to Python 2, is not installed.
SyntaxError: future feature annotations is not defined
The `from __future__ import annotations` syntax, introduced by PEP 563, is only available from Python 3.7 onwards. This error occurs when trying to use it in an older Python version.
fixUpgrade your Python interpreter to version 3.7 or newer, or remove the `from __future__ import annotations` statement if it's not critical for older Python versions.
SyntaxError: future feature print_function is not defined
This error occurs in Python 2 when `from __future__ import print_function` is used with a Python 2 version older than 2.6, as the print function feature was introduced in Python 2.6.
fixUpgrade your Python 2 interpreter to version 2.6 or newer, or ensure the code using this future import is not run on older Python 2 versions.
SyntaxError: invalid syntax (with 'L' suffix on numbers)
Python 2 used an 'L' suffix (e.g., `1234L`) to denote long integers. Python 3 merged 'int' and 'long' types, making the 'L' suffix invalid syntax.
fixRemove the 'L' suffix from integer literals. The `futurize` script from the 'future' library can help automate this conversion across your codebase by running `futurize -w your_script.py`.
Audit
Dependencies
No dependency data recorded yet.