Python eval(): Evaluate Expressions Dynamically

The First Argument: expression

The first argument to eval() is called expression. It’s a required argument that holds the string-based or compiled-code-based input to the function. When you call eval(), the content of expression is evaluated as a Python expression. Check out the following examples that use string-based input:

>>> eval("2 ** 8")
256
>>> eval("1024 + 1024")
2048
>>> eval("sum([8, 16, 32])")
56
>>> x = 100
>>> eval("x * 2")
200

When you call eval() with a string as an argument, the function returns the value that results from evaluating the input string. By default, eval() has access to global names like x in the above example.

To evaluate a string-based expression, Python’s eval() runs the following steps:

1. Parse expression
2. Compile it to bytecode
3. Evaluate it as a Python expression
4. Return the result of the evaluation

The name expression for the first argument to eval() highlights that the function works only with expressions and not with compound statements. The Python documentation defines expression as follows:

expression

A piece of syntax which can be evaluated to some value. In other words, an expression is an accumulation of expression elements like literals, names, attribute access, operators or function calls which all return a value. In contrast to many other languages, not all language constructs are expressions. There are also statements which cannot be used as expressions, such as while. Assignments are also statements, not expressions. (Source)

On the other hand, a Python statement has the following definition:

statement

A statement is part of a suite (a “block” of code). A statement is either an expression or one of several constructs with a keyword, such as if, while or for. (Source)

If you try to pass a compound statement to eval(), then you’ll get a SyntaxError. Take a look at the following example in which you try to execute an if statement using eval():

>>> x = 100
>>> eval("if x: print(x)")
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "<string>", line 1
    if x: print(x)
    ^
SyntaxError: invalid syntax

If you try to evaluate a compound statement using Python’s eval(), then you’ll get a SyntaxError like in the above traceback. That’s because eval() only accepts expressions. Any other statement, such as if, for, while, import, def, or class, will raise an error.

Assignment operations aren’t allowed with eval() either:

>>> eval("pi = 3.1416")
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "<string>", line 1
    pi = 3.1416
       ^
SyntaxError: invalid syntax

If you try to pass an assignment operation as an argument to Python’s eval(), then you’ll get a SyntaxError. Assignment operations are statements rather than expressions, and statements aren’t allowed with eval().

You’ll also get a SyntaxError any time the parser doesn’t understand the input expression. Take a look at the following example in which you try to evaluate an expression that violates Python syntax:

>>> # Incomplete expression
>>> eval("5 + 7 *")
Traceback (most recent call last):
  File "<input>", line 1, in <module>
    eval("5 + 7 *")
  File "<string>", line 1
    5 + 7 *
          ^
SyntaxError: unexpected EOF while parsing

You can’t pass an expression to eval() that violates Python syntax. In the above example, you try to evaluate an incomplete expression ("5 + 7 *") and get a SyntaxError because the parser doesn’t understand the syntax of the expression.

You can also pass compiled code objects to Python’s eval(). To compile the code that you’re going to pass to eval(), you can use compile(). This is a built-in function that can compile an input string into a code object or an AST object so that you can evaluate it with eval().

The details of how to use compile() are beyond the scope of this tutorial, but here’s a quick look at its first three required arguments:

1. source holds the source code that you want to compile. This argument accepts normal strings, byte strings, and AST objects.
2. filename gives the file from which the code was read. If you’re going to use a string-based input, then the value for this argument should be "<string>".
3. mode specifies which kind of compiled code you want to get. If you want to process the compiled code with eval(), then this argument should be set to "eval".

You can use compile() to supply code objects to eval() instead of normal strings. Check out the following examples:

>>> # Arithmetic operations
>>> code = compile("5 + 4", "<string>", "eval")
>>> eval(code)
9
>>> code = compile("(5 + 7) * 2", "<string>", "eval")
>>> eval(code)
24
>>> import math
>>> # Volume of a sphere
>>> code = compile("4 / 3 * math.pi * math.pow(25, 3)", "<string>", "eval")
>>> eval(code)
65449.84694978735

If you use compile() to compile the expressions that you’re going to pass to eval(), then eval() goes through the following steps:

1. Evaluate the compiled code
2. Return the result of the evaluation

If you call Python’s eval() using a compiled-code-based input, then the function performs the evaluation step and immediately returns the result. This can be handy when you need to evaluate the same expression multiple times. In this case, it’s best to precompile the expression and reuse the resulting bytecode on subsequent calls to eval().

If you compile the input expression beforehand, then successive calls to eval() will run faster because you won’t be repeating the parsing and compiling steps. Unneeded repetitions can lead to high CPU times and excessive memory consumption if you’re evaluating complex expressions.

The Second Argument: globals

The second argument to eval() is called globals. It’s optional and holds a dictionary that provides a global namespace to eval(). With globals, you can tell eval() which global names to use while evaluating expression.

Global names are all those names that are available in your current global scope or namespace. You can access them from anywhere in your code.

All the names passed to globals in a dictionary will be available to eval() at execution time. Check out the following example, which shows how to use a custom dictionary to supply a global namespace to eval():

>>> x = 100  # A global variable
>>> eval("x + 100", {"x": x})
200
>>> y = 200  # Another global variable
>>> eval("x + y", {"x": x})
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "<string>", line 1, in <module>
NameError: name 'y' is not defined

If you supply a custom dictionary to the globals argument of eval(), then eval() will take only those names as globals. Any global names defined outside of this custom dictionary won’t be accessible from inside eval(). That’s why Python raises a NameError when you try to access y in the above code: The dictionary passed to globals doesn’t include y.

You can insert names into globals by listing them in your dictionary, and then those names will be available during the evaluation process. For example, if you insert y into globals, then the evaluation of "x + y" in the above example will work as expected:

>>> eval("x + y", {"x": x, "y": y})
300

Since you add y to your custom globals dictionary, the evaluation of "x + y" is successful and you get the expected return value of 300.

You can also supply names that don’t exist in your current global scope. For this to work, you need to supply a concrete value for each name. eval() will interpret these names as global names when running:

>>> eval("x + y + z", {"x": x, "y": y, "z": 300})
600
>>> z
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
NameError: name 'z' is not defined

Even though z isn’t defined in your current global scope, the variable is present in globals with a value of 300. In this case, eval() has access to z as though it were a global variable.

The mechanism behind globals is quite flexible. You can pass any visible variable (global, local, or nonlocal) to globals. You can also pass custom key-value pairs like "z": 300 in the above example. eval() will treat all of them as global variables.

An important point regarding globals is that if you supply a custom dictionary to it that doesn’t contain a value for the key "__builtins__", then a reference to the dictionary of builtins will be automatically inserted under "__builtins__" before expression gets parsed. This ensures that eval() will have full access to all of Python’s built-in names when evaluating expression.

The following examples show that even though you supply an empty dictionary to globals, the call to eval() will still have access to Python’s built-in names:

>>> eval("sum([2, 2, 2])", {})
6
>>> eval("min([1, 2, 3])", {})
1
>>> eval("pow(10, 2)", {})
100

In the above code, you supply an empty dictionary ({}) to globals. Since that dictionary doesn’t contain a key called "__builtins__", Python automatically inserts one with a reference to the names in builtins. This way, eval() has full access to all of Python’s built-in names when it parses expression.

If you call eval() without passing a custom dictionary to globals, then the argument will default to the dictionary returned by globals() in the environment where eval() is called:

>>> x = 100  # A global variable
>>> y = 200  # Another global variable
>>> eval("x + y")  # Access both global variables
300

When you call eval() without supplying a globals argument, the function evaluates expression using the dictionary returned by globals() as its global namespace. So, in the above example, you can freely access x and y because they’re global variables included in your current global scope.

The Third Argument: locals

Python’s eval() takes a third argument called locals. This is another optional argument that holds a dictionary. In this case, the dictionary contains the variables that eval() uses as local names when evaluating expression.

Local names are those names (variables, functions, classes, and so on) that you define inside a given function. Local names are visible only from inside the enclosing function. You define these kinds of names when you’re writing a function.

Since eval() is already written, you can’t add local names to its code or local scope. However, you can pass a dictionary to locals, and eval() will treat those names as local names:

>>> eval("x + 100", {}, {"x": 100})
200
>>> eval("x + y", {}, {"x": 100})
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "<string>", line 1, in <module>
NameError: name 'y' is not defined

The second dictionary in the first call to eval() holds the variable x. This variable is interpreted by eval() as a local variable. In other words, it’s seen as a variable defined in the body of eval().

You can use x in expression, and eval() will have access to it. In contrast, if you try to use y, then you’ll get a NameError because y isn’t defined in either the globals namespace or the locals namespace.

Like with globals, you can pass any visible variable (global, local, or nonlocal) to locals. You can also pass custom key-value pairs like "x": 100 in the above example. eval() will treat all of them as local variables.

Note that to supply a dictionary to locals, you first need to supply a dictionary to globals. It’s not possible to use keyword arguments with eval():

>>> eval("x + 100", locals={"x": 100})
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: eval() takes no keyword arguments

If you try to use keyword arguments when calling eval(), then you’ll get a TypeError explaining that eval() takes no keyword arguments. So, you need to supply a globals dictionary before you can supply a locals dictionary.

If you don’t pass a dictionary to locals, then it defaults to the dictionary passed to globals. Here’s an example in which you pass an empty dictionary to globals and nothing to locals:

>>> x = 100
>>> eval("x + 100", {})
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "<string>", line 1, in <module>
NameError: name 'x' is not defined

Given that you don’t provide a custom dictionary to locals, the argument defaults to the dictionary passed to globals. In this case, eval() doesn’t have access to x because globals holds an empty dictionary.

The main practical difference between globals and locals is that Python will automatically insert a "__builtins__" key into globals if that key doesn’t already exist. This happens whether or not you supply a custom dictionary to globals. On the other hand, if you supply a custom dictionary to locals, then that dictionary will remain unchanged during the execution of eval().

Boolean Expressions

Boolean expressions are Python expressions that return a truth value (True or False) when the interpreter evaluates them. They’re commonly used in if statements to check if some condition is true or false. Since Boolean expressions aren’t compound statements, you can use eval() to evaluate them:

>>> x = 100
>>> y = 100
>>> eval("x != y")
False
>>> eval("x < 200 and y > 100")
False
>>> eval("x is y")
True
>>> eval("x in {50, 100, 150, 200}")
True

You can use eval() with Boolean expressions that use any of the following Python operators:

• Value comparison operators: <, >, <=, >=, ==, !=
• Logical (Boolean) operators: and, or, not
• Membership test operators: in, not in
• Identity operators: is, is not

In all cases, the function returns the truth value of the expression that you’re evaluating.

Now, you may be thinking, why should I use eval() instead of using the Boolean expression directly? Well, suppose you need to implement a conditional statement, but you want to change the condition on the fly:

>>> def func(a, b, condition):
...     if eval(condition):
...         return a + b
...     return a - b
...
>>> func(2, 4, "a > b")
-2
>>> func(2, 4, "a < b")
6
>>> func(2, 2, "a is b")
4

Inside func(), you use eval() to evaluate the supplied condition and return either a + b or a - b according to the result of the evaluation. You use just a few different conditions in the above example, but you could use any number of others provided that you stick with the names a and b that you defined in func().

Now imagine how you would implement something like this without the use of Python’s eval(). Would that take less code and time? No way!

Math Expressions

One common use case of Python’s eval() is to evaluate math expressions from a string-based input. For example, if you want to create a Python calculator, then you can use eval() to evaluate the user’s input and return the result of the calculations.

The following examples show how you can use eval() along with math to perform math operations:

>>> # Arithmetic operations
>>> eval("5 + 7")
12
>>> eval("5 * 7")
35
>>> eval("5 ** 7")
78125
>>> eval("(5 + 7) / 2")
6.0
>>> import math
>>> # Area of a circle
>>> eval("math.pi * pow(25, 2)")
1963.4954084936207
>>> # Volume of a sphere
>>> eval("4 / 3 * math.pi * math.pow(25, 3)")
65449.84694978735
>>> # Hypotenuse of a right triangle
>>> eval("math.sqrt(math.pow(10, 2) + math.pow(15, 2))")
18.027756377319946

When you use eval() to evaluate math expressions, you can pass in expressions of any kind or complexity. eval() will parse them, evaluate them and, if everything is okay, give you the expected result.

General-Purpose Expressions

So far, you’ve learned how to use eval() with Boolean and math expressions. However, you can use eval() with more complex Python expressions that incorporate function calls, object creation, attribute access, comprehensions, and so on.

For example, you can call a built-in function or one that you’ve imported with a standard or third-party module:

>>> # Run the echo command
>>> import subprocess
>>> eval("subprocess.getoutput('echo Hello, World')")
'Hello, World'
>>> # Launch Firefox (if available)
>>> eval("subprocess.getoutput('firefox')")
''

In this example, you use Python’s eval() to execute a few system commands. As you can imagine, you can do a ton of useful things with this feature. However, eval() can also expose you to serious security risks, like allowing a malicious user to run system commands or any arbitrary piece of code in your machine.

In the next section, you’ll look at ways to address some of the security risks associated with eval().

Restricting globals and locals

You can restrict the execution environment of eval() by passing custom dictionaries to the globals and locals arguments. For example, you can pass empty dictionaries to both arguments to prevent eval() from accessing names in the caller’s current scope or namespace:

>>> # Avoid access to names in the caller's current scope
>>> x = 100
>>> eval("x * 5", {}, {})
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "<string>", line 1, in <module>
NameError: name 'x' is not defined

If you pass empty dictionaries ({}) to globals and locals, then eval() won’t find the name x in either its global namespace or its local namespace when evaluating the string "x * 5". As a result, eval() will throw a NameError.

Unfortunately, restricting the globals and locals arguments like this doesn’t eliminate all the security risks associated with the use of Python’s eval(), because you can still access all of Python’s built-in names.

Restricting the Use of Built-In Names

As you saw earlier, Python’s eval() automatically inserts a reference to the dictionary of builtins into globals before parsing expression. A malicious user could exploit this behavior by using the built-in function __import__() to get access to the standard library and any third-party module that you’ve installed on your system.

The following examples show that you can use any built-in function and any standard module like math or subprocess even after you’ve restricted globals and locals:

>>> eval("sum([5, 5, 5])", {}, {})
15
>>> eval("__import__('math').sqrt(25)", {}, {})
5.0
>>> eval("__import__('subprocess').getoutput('echo Hello, World')", {}, {})
'Hello, World'

Even though you restrict globals and locals using empty dictionaries, you can still use any built-in function like you did with sum() and __import__() in the above code.

You can use __import__() to import any standard or third-party module just like you did above with math and subprocess. With this technique, you can access any function or class defined in math, subprocess, or any other module. Now imagine what a malicious user could do to your system using subprocess or any other powerful module in the standard library.

To minimize this risk, you can restrict access to Python’s built-in functions by overriding the "__builtins__" key in globals. Good practice recommends using a custom dictionary containing the key-value pair "__builtins__": {}. Check out the following example:

>>> eval("__import__('math').sqrt(25)", {"__builtins__": {}}, {})
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "<string>", line 1, in <module>
NameError: name '__import__' is not defined

If you pass a dictionary containing the key-value pair "__builtins__": {} to globals, then eval() won’t have direct access to Python’s built-in functions like __import__(). However, as you’ll see in the next section, this approach still doesn’t make eval() completely secure.

Restricting Names in the Input

Even though you can restrict the execution environment of Python’s eval() using custom globals and locals dictionaries, the function will still be vulnerable to a few fancy tricks. For example, you can access the class object using a type literal like "", [], {}, or () along with some special attributes:

>>> "".__class__.__base__
<class 'object'>
>>> [].__class__.__base__
<class 'object'>
>>> {}.__class__.__base__
<class 'object'>
>>> ().__class__.__base__
<class 'object'>

Once you have access to object, you can use a special method, .__subclasses__(), to get access to all of the classes that inherit from object. Here’s how it works:

>>> for sub_class in ().__class__.__base__.__subclasses__():
...     print(sub_class.__name__)
...
type
weakref
weakcallableproxy
weakproxy
int
...

This code will print a large list of classes to your screen. Some of these classes are quite powerful and can be extremely dangerous in the wrong hands. This opens up another important security hole that you can’t close by simply restricting the execution environment of eval():

>>> input_string = """[
...     c for c in ().__class__.__base__.__subclasses__()
...     if c.__name__ == "range"
... ][0](10)"""
>>> list(eval(input_string, {"__builtins__": {}}, {}))
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]

The list comprehension in the above code filters the classes that inherit from object to return a list containing the class range. The first index ([0]) returns the class range. Once you have access to range, you call it to generate a range object. Then you call list() on the range object to generate a list of ten integers.

In this example, you use range to illustrate a security hole in eval(). Now imagine what a malicious user could do if your system exposed classes like subprocess.Popen.

A possible solution to this vulnerability is to restrict the use of names in the input, either to a bunch of safe names or to no names at all. To implement this technique, you need to go through the following steps:

1. Create a dictionary containing the names that you want to use with eval().
2. Compile the input string to bytecode using compile() in mode "eval".
3. Check .co_names on the bytecode object to make sure it contains only allowed names.
4. Raise a NameError if the user tries to enter a name that’s not allowed.

Take a look at the following function in which you implement all these steps:

>>> def eval_expression(input_string):
...     # Step 1
...     allowed_names = {"sum": sum}
...     # Step 2
...     code = compile(input_string, "<string>", "eval")
...     # Step 3
...     for name in code.co_names:
...         if name not in allowed_names:
...             # Step 4
...             raise NameError(f"Use of {name} not allowed")
...     return eval(code, {"__builtins__": {}}, allowed_names)

In eval_expression(), you implement all of the steps you saw before. This function restricts the names that you can use with eval() to only those names in the dictionary allowed_names. To do this, the function uses .co_names, which is an attribute of a code object that returns a tuple containing the names in the code object.

The following examples show how eval_expression() works in practice:

>>> eval_expression("3 + 4 * 5 + 25 / 2")
35.5
>>> eval_expression("sum([1, 2, 3])")
6
>>> eval_expression("len([1, 2, 3])")
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "<stdin>", line 10, in eval_expression
NameError: Use of len not allowed
>>> eval_expression("pow(10, 2)")
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "<stdin>", line 10, in eval_expression
NameError: Use of pow not allowed

If you call eval_expression() to evaluate arithmetic operations, or if you use expressions that include allowed names, then you’ll get the expected result. Otherwise, you’ll get a NameError. In the above examples, the only name you’ve allowed is sum(). Other names like len() and pow() are not allowed, so the function raises a NameError when you try to use them.

If you want to completely disallow the use of names, then you can rewrite eval_expression() as follows:

>>> def eval_expression(input_string):
...     code = compile(input_string, "<string>", "eval")
...     if code.co_names:
...         raise NameError(f"Use of names not allowed")
...     return eval(code, {"__builtins__": {}}, {})
...
>>> eval_expression("3 + 4 * 5 + 25 / 2")
35.5
>>> eval_expression("sum([1, 2, 3])")
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "<stdin>", line 4, in eval_expression
NameError: Use of names not allowed

Now your function doesn’t allow any names in the input string. To accomplish this, you check for names in .co_names and raise a NameError if one is found. Otherwise, you evaluate input_string and return the result of the evaluation. In this case, you use an empty dictionary to restrict locals as well.

You can use this technique to minimize the security issues of eval() and strengthen your armor against malicious attacks.

Restricting the Input to Only Literals

A common use case for Python’s eval() is to evaluate strings that contain standard Python literals and turn them into concrete objects.

The standard library provides a function called literal_eval() that can help achieve this goal. The function doesn’t support operators, but it does support lists, tuples, numbers, strings, and so on:

>>> from ast import literal_eval
>>> # Evaluating literals
>>> literal_eval("15.02")
15.02
>>> literal_eval("[1, 15]")
[1, 15]
>>> literal_eval("(1, 15)")
(1, 15)
>>> literal_eval("{'one': 1, 'two': 2}")
{'one': 1, 'two': 2}
>>> # Trying to evaluate an expression
>>> literal_eval("sum([1, 15]) + 5 + 8 * 2")
Traceback (most recent call last):
  ...
ValueError: malformed node or string: <_ast.BinOp object at 0x7faedecd7668>

Notice that literal_eval() only works with standard type literals. It doesn’t support the use of operators or names. If you try to feed an expression to literal_eval(), then you’ll get a ValueError. This function can also help you minimize the security risks associated with the use of Python’s eval().