Using the sys Module

The sys module is useful when a program needs to inspect information connected to the way it was started or the Python version running it.

Programming

When a Program Meets Its Environment

A Python program does not run in isolation. It can receive command-line input and inspect information about the Python version in which it is running. The sys module provides system-specific functionality and acts as an interface between Python and the operating system. In this article, you will trace two especially useful parts of that interface: sys.argv for command-line arguments and sys.version_info for Python version information.

Key point

The sys module is useful when a program needs to inspect information connected to the way it was started or the Python version running it.

How does information move between the operating system and a running Python program through the sys module?

Tracing Command-Line Arguments

sys.argv is a list containing the command-line arguments used to start a Python program. Its first element, sys.argv[0], is always the script name. Additional command-line words appear at later indices, beginning with sys.argv[1]. This means the list preserves an order that a program can inspect.

How do the command-line words become ordered values in sys.argv, and what does each index contain?

Worked example

Mapping a Command to sys.argv

Suppose the script is started with python demo.py hello world. What values should appear in sys.argv?

1
Identify the script name
The script name occupies sys.argv[0], so the first value is demo.py.
2
Read the first user argument
The word hello follows the script name, so it occupies sys.argv[1].
3
Read the second user argument
The word world follows hello, so it occupies sys.argv[2].

Result

sys.argv is ['demo.py', 'hello', 'world'], and len(sys.argv) is 3.

Inspecting Python Version Information

sys.version_info is a tuple containing Python version details. One useful component is the major version, which you can access with sys.version_info.major. Checking this value lets a program determine whether it is running Python 3.

What information is contained in sys.version_info, and how is the major version accessed?

python

import sys

print(sys.version_info)
print(sys.version_info.major)

import sys

print(sys.version_info)
print(sys.version_info.major)

The first print displays the version information contained in sys.version_info. The second print selects the major component directly. For example, the source demonstration reports Python 3.11.7, so the major version is 3.

Predicting the Initial Values

What do you think happens?

If a script is run without additional command-line arguments, what will sys.argv contain, and what major version will a Python 3 interpreter report?

sys.argv contains only the script name, and the major version is 3
sys.argv is empty, and the major version is 0
sys.argv contains two arguments, and the major version is 11

Reveal answer

Answer:

sys.argv contains only the script name, and the major version is 3.

sys.argv[0] is always the script name. With no additional arguments, there are no later elements. The major version is accessed with sys.version_info.major, which is 3 when the program is running Python 3.

Code walkthrough

import sys

print(sys.argv)
print(sys.version_info.major)

1
The import statement makes the sys module available to the program.
2
Because the script was run without additional arguments, sys.argv contains one element: the script name.
3
The major version is 3 when the program is running Python 3.

Import sys so the program can access sys.argv and sys.version_info.
Print the complete list of command-line arguments.
Print the major Python version.

Output

['demo.py']
3

The important trace is that the list does not begin with the first word typed after the script name. The script name is already at index 0. Only words added after it become user-provided arguments at later indices.

Using Checks During Debugging

When a program behaves unexpectedly, inspect the information it received before investigating more complex logic. Printing sys.argv can show whether the expected command-line words arrived and whether they are in the expected order. Checking sys.version_info.major can show whether the program is running Python 3.

What sequence of checks can a program follow to inspect its Python version and command-line inputs before continuing?

python

import sys

print("Python major version:", sys.version_info.major)
print("Command-line values:", sys.argv)

import sys

print("Python major version:", sys.version_info.major)
print("Command-line values:", sys.argv)

Mistakes with sys Values

Common mistake
Treating sys.argv[0] as the first user-provided argument.
What it looks like
Assuming sys.argv[0] is hello when the command is python demo.py hello.
Why it fails
sys.argv[0] is always the script name.
Do this instead
Read the first user-provided argument at sys.argv[1].
Common mistake
Treating a value from sys.argv as a number automatically.
What it looks like
Using a value from sys.argv directly in arithmetic because it looks like 10.
Why it fails
All values in sys.argv are strings, even when they look like numbers.
Do this instead
Convert the value to int or float when arithmetic is needed.
Common mistake
Assuming sys.argv is empty when no extra arguments are supplied.
What it looks like
Expecting no values after running a script without additional arguments.
Why it fails
The script name still occupies sys.argv[0].
Do this instead
Expect one element when there are no additional command-line arguments.
Common mistake
Checking the complete version information when only the major version is needed.
What it looks like
Inspecting the entire sys.version_info value just to determine whether Python 3 is running.
Why it fails
The major component directly answers that particular question.
Do this instead
Use sys.version_info.major to check the major version.

Practice: Trace the Inputs

EASY

A script named report.py is run with the command python report.py weekly 7. Write the expected values for sys.argv[0], sys.argv[1], and sys.argv[2]. Then state whether the value at sys.argv[2] is a string or a number before conversion.

Hints

The script name occupies index 0.
The words after the script name occupy later indices in order.
Every value in sys.argv is a string.

Your attempt (not saved)

MEDIUM

Write a short Python program that imports sys, prints sys.version_info.major, and prints sys.argv. Run it once without extra arguments and once with two extra words. Compare how the list changes.

Hints

Use import sys before accessing either value.
Print sys.version_info.major for the major version.
Print sys.argv to inspect the complete ordered list.

Your attempt (not saved)

Key Takeaways

1
The sys module provides system-specific functionality and acts as an interface between Python and the operating system.
2
sys.argv is an ordered list of command-line arguments; sys.argv[0] is always the script name.
3
All values in sys.argv are strings, so convert them to int or float when arithmetic is required.
4
sys.version_info contains Python version details, and sys.version_info.major gives the major version.
5
Printing sys.argv and checking sys.version_info.major are practical first checks when debugging command-line input and Python-version problems.

At a glance

sys provides an interface to system-specific functionality available to a running Python program.
sys.argv records the script name and any additional command-line arguments in order.
sys.version_info.major provides a direct way to check the Python major version.
Inspecting these values can reveal incorrect command-line inputs or an unexpected Python version during debugging.

Related concepts

More concepts starting with U

When a Program Meets Its Environment

Tracing Command-Line Arguments

Inspecting Python Version Information

Predicting the Initial Values

Using Checks During Debugging

Mistakes with sys Values

Practice: Trace the Inputs

Key Takeaways

At a glance

Related Topics

Related concepts