Skip to main content

How to Solve "SyntaxError: future feature annotations is not defined" in Python

The SyntaxError: future feature annotations is not defined error occurs when you use the from __future__ import annotations statement in a Python version older than 3.7. This statement enables postponed evaluation of type hints, a feature introduced in Python 3.7.

This guide explains the error and provides solutions, focusing on upgrading Python or adapting your code.

Understanding the Error​

The from __future__ import annotations statement changes how Python handles type hints. Before Python 3.7, this statement was not recognized, leading to the SyntaxError. In Python 3.7 and later, it postpones the evaluation of type hints, which can be helpful for:

  • Forward References: Allowing type hints to refer to classes that haven't been defined yet.
  • Circular Dependencies: Breaking circular dependencies between modules that use type hints.
  • Performance: Slightly improving startup time by delaying type hint evaluation.

However, if your code must run on older Python versions, you'll need to adapt it.

Solutions​

The simplest and best solution is to upgrade your Python installation to version 3.7 or later. This will allow you to use the annotations feature directly. Check your current version with:

python --version  # Or python3 --version, or py --version on Windows

If your version is below 3.7, upgrade.

Remove the from __future__ import annotations Statement (If Possible)​

If you can modify the code and the benefits of postponed evaluation aren't essential, simply remove the import statement:

# main.py (Python 3.6 or earlier)
# from __future__ import annotations  # REMOVE THIS LINE

print('tutorialreference.com')  # This will now work on older Python versions

Before removing the line make sure you are not using any feature that relies on that:

from __future__ import annotations
class MyClass:
    def method(self, param: 'MyClass'): # Using the class type in an annotation
        ... some code ...

In this case, removing the line will cause an error, so it is not possible.

Use string type hints instead of annotations​

If you want to avoid using annotations, you can refactor to using string type hints.

class MyClass:
    def method(self, param: 'MyClass'): # Using a string
        ... some code ...

Conditional Import (For Backward Compatibility - Advanced)​

If you need to support both older and newer Python versions, you can use a conditional import. This is more complex but allows for maximum compatibility:

import sys

if sys.version_info >= (3, 7):
    from __future__ import annotations
    print('tutorialreference.com using annotation.')
else:
    print('tutorialreference.com without using annotation.')
  • sys.version_info: This provides a tuple representing the Python version (e.g., (3, 6, 15) for Python 3.6.15).
  • sys.version_info >= (3, 7): This checks if the Python version is 3.7 or greater.
  • Only if the version is 3.7 or greater is the import executed.

Creating a Virtual Environment with a Specific Python Version​

If you have a newer Python version installed somewhere on your system, but it's not the default, you can create a virtual environment that uses it:

# Example using Python 3.9.  Replace with your desired version.
python3.9 -m venv venv      # Create the environment
source venv/bin/activate    # Activate (Linux/macOS)
venv\Scripts\activate       # Activate (Windows - cmd.exe)
venv\Scripts\Activate.ps1   # Activate (Windows - powershell)
python --version            # Verify the correct version is active
  • Using this approach you can specify the python version used in the virtual environment.

Installing a Newer Python Version with Anaconda​

If you use Anaconda, you can easily install and manage multiple Python versions:

conda install python=3.10  # Install Python 3.10 (replace with your desired version)
conda create --name my_env python=3.10 #Or, create environment

Installing a Newer Python Version Directly​

If you don't have a newer Python version, download and install it from the official Python website (https://www.python.org/downloads/).

Make sure to choose the correct installer for your operating system.

Conclusion​

The SyntaxError: future feature annotations is not defined error is a clear indicator that your Python version is too old to support the from __future__ import annotations statement.

The best solution is to upgrade to Python 3.7 or later. If that's not possible, you can remove the import statement (if the code's functionality isn't critically dependent on it) or use a conditional import for backward compatibility.

Using virtual environments allows you to manage different Python versions for different projects, which is strongly recommended.

Table of Contents