1. Línea de comandos y entorno¶

1.1.1. Opciones de interfaz¶

La interfaz del intérprete es similar a la del shell UNIX, pero proporciona algunos métodos adicionales de invocación:

• When called with standard input connected to a tty device, it prompts for commands and executes them until an EOF (an end-of-file character, you can produce that with Ctrl-D on UNIX or Ctrl-Z, Enter on Windows) is read. For more on interactive mode, see Modo interactivo.

• Cuando se llama con un argumento de nombre de archivo o con un archivo como entrada estándar, lee y ejecuta un script de ese archivo.

• Cuando se llama con un argumento de nombre de directorio, lee y ejecuta un script con el nombre adecuado desde ese directorio.

• Cuando se llama con -c comando, ejecuta las instrucciones de Python dadas como command. Aquí comando puede contener varias instrucciones separadas por nuevas líneas. ¡El espacio en blanco principal es significativo en las instrucciones de Python!

• Cuando se llama con -m module-name, el módulo dado se encuentra en la ruta del módulo Python y se ejecuta como un script.

En el modo no interactivo, toda la entrada se analiza antes de ejecutarse.

Una opción de interfaz termina la lista de opciones consumidas por el intérprete, todos los argumentos consecutivos terminarán en sys.argv – tenga en cuenta que el primer elemento, subíndice cero (sys.argv[0]), es una cadena que refleja el origen del programa.

-c <command>¶

Ejecute el código de Python en comando. comando puede ser una o más sentencias separadas por nuevas líneas, con espacio en blanco inicial significativo como en el código normal del módulo.

Si se proporciona esta opción, el primer elemento de sys.argv será "-c" y el directorio actual se agregará al inicio de sys.path (permitiendo que los módulos de ese directorio se importen como módulos de nivel superior).

Lanza un auditing event cpython.run_command con el argumento command.

Distinto en la versión 3.14: command is automatically dedented before execution.

-m <module-name>¶

Busque sys.path para el módulo con nombre y ejecute su contenido como el módulo __main__.

Dado que el argumento es un nombre módulo, no debe dar una extensión de archivo (.py). El nombre del módulo debe ser un nombre de módulo Python absoluto válido, pero es posible que la implementación no siempre lo aplique (por ejemplo, puede permitirle usar un nombre que incluya un guión).

También se permiten los nombres de paquetes (incluidos los paquetes de espacio de nombres). Cuando se proporciona un nombre de paquete en lugar de un módulo normal, el intérprete ejecutará <pkg>.__main__ como módulo principal. Este comportamiento es deliberadamente similar al manejo de directorios y archivos zip que se pasan al intérprete como argumento del script.

Nota

Esta opción no se puede utilizar con módulos integrados y módulos de extensión escritos en C, ya que no tienen archivos de módulo Python. Sin embargo, todavía se puede utilizar para módulos precompilados, incluso si el archivo de origen original no está disponible.

Si se da esta opción, el primer elemento de sys.argv será la ruta de acceso completa al archivo de módulo (mientras se encuentra el archivo de módulo, el primer elemento se establecerá en "-m"). Al igual que con la opción -c, el directorio actual se agregará al inicio de sys.path.

-I option can be used to run the script in isolated mode where sys.path contains neither the current directory nor the user’s site-packages directory. All PYTHON* environment variables are ignored, too.

Muchos módulos de biblioteca estándar contienen código que se invoca en su ejecución como script. Un ejemplo es el módulo timeit:

python -m timeit -s "setup here" "benchmarked code here"
python -m timeit -h # for details

Retorna un auditing event cpython.run_module con el argumento nombre-módulo.

Ver también

runpy.run_module()

Funcionalidad equivalente directamente disponible para el código Python

PEP 338 – Ejecución de módulos como scripts

Distinto en la versión 3.1: Proporcione el nombre del paquete para ejecutar un submódulo __main__.

Distinto en la versión 3.4: paquetes de espacio de nombres también son compatibles

-

Leer comandos de entrada estándar (sys.stdin). Si la entrada estándar es un terminal, -i está implícita.

Si se da esta opción, el primer elemento de sys.argv será "-" y el directorio actual se agregará al inicio de sys.path.

Lanza un evento auditing event cpython.run_stdin sin argumentos.

<script>

Ejecute el código Python contenido en script, que debe ser una ruta de acceso del sistema de archivos (absoluta o relativa) que haga referencia a un archivo Python, un directorio que contenga un archivo __main__.py o un archivo zip que contenga un archivo __main__.py.

Si se proporciona esta opción, el primer elemento de sys.argv será el nombre del script como se indica en la línea de comandos.

Si el nombre del script hace referencia directamente a un archivo Python, el directorio que contiene ese archivo se agrega al inicio de sys.path, y el archivo se ejecuta como el módulo __main__.

Si el nombre del script hace referencia a un directorio o zipfile, el nombre del script se agrega al inicio de sys.path y el archivo __main__.py en esa ubicación se ejecuta como el módulo __main__.

-I option can be used to run the script in isolated mode where sys.path contains neither the script’s directory nor the user’s site-packages directory. All PYTHON* environment variables are ignored, too.

Lanza un auditing event cpython.run_file con el argumento filename.

Ver también

runpy.run_path()

Funcionalidad equivalente directamente disponible para el código Python

Si no se da ninguna opción de interfaz, -i está implícita, sys.argv[0] es una cadena vacía (") y el directorio actual se agregará al inicio de sys.path. Además, la finalización de tabulación y la edición del historial se habilitan automáticamente, si están disponibles en su plataforma (consulte Configuración de Readline).

1.1.2. Opciones genéricas¶

-?¶

-h¶

--help¶

Imprime una breve descripción de todas las opciones de la línea de comandos.

--help-env¶

Imprima una breve descripción de las variables de entorno específicas de Python y salga.

Added in version 3.11.

--help-xoptions¶

Imprima una descripción de las opciones -X específicas de la implementación y salga.

Added in version 3.11.

--help-all¶

Imprima información completa de uso y salga.

Added in version 3.11.

-V¶

--version¶

Imprima el número de versión de Python y salga. Ejemplo de salida podría ser:

Python 3.8.0b2+

Cuando se le dé dos veces, imprima más información sobre la compilación, como:

Python 3.8.0b2+ (3.8:0c076caaa8, Apr 20 2019, 21:55:00)
[GCC 6.2.0 20161005]

Added in version 3.6: La opción -VV.

1.1.3. Opciones diversas¶

-b¶

Issue a warning when converting bytes or bytearray to str without specifying encoding or comparing bytes or bytearray with str or bytes with int. Issue an error when the option is given twice (-bb).

Distinto en la versión 3.5: Affects also comparisons of bytes with int.

-B¶

Si se da, Python no intentará escribir archivos .pyc en la importación de módulos de origen. Véase también PYTHONDONTWRITEBYTECODE.

--check-hash-based-pycs default|always|never¶

Controle el comportamiento de validación de los archivos .pyc basados en hash. Véase Invalidación del código de bytes en caché. Cuando se establece en default, los archivos de caché de código de bytes basados en hash marcados y desmarcados se validan según su semántica predeterminada. Cuando se establece en always, todos los archivos basados en hash .pyc, ya estén marcados o desmarcados, se validan con su archivo de origen correspondiente. Cuando se establece en never, los archivos basados en hash .pyc no se validan con sus archivos de origen correspondientes.

Esta opción no afecta a la semántica de los archivos .pyc basados en la marca de tiempo.

-d¶

Activa la salida de depuración (solo para expertos, dependiendo de las opciones de compilación). Véase también la variable de ambiente PYTHONDEBUG.

Esta opción necesita una compilación de depuración de Python, de lo contrario será ignorado.

-E¶

Ignore all PYTHON* environment variables, e.g. PYTHONPATH and PYTHONHOME, that might be set.

Véase también las opciones -P e -I (aisladas).

-i¶

Enter interactive mode after execution.

Using the -i option will enter interactive mode in any of the following circumstances:

• When a script is passed as first argument

• When the -c option is used

• When the -m option is used

Interactive mode will start even when sys.stdin does not appear to be a terminal. The PYTHONSTARTUP file is not read.

Esto puede ser útil para inspeccionar variables globales o un seguimiento de pila cuando un script lanza una excepción. Véase también PYTHONINSPECT.

-I¶

Ejecute Python en modo aislado. Esto también implica las opciones -E, -P y -s.

In isolated mode sys.path contains neither the script’s directory nor the user’s site-packages directory. All PYTHON* environment variables are ignored, too. Further restrictions may be imposed to prevent the user from injecting malicious code.

Added in version 3.4.

-O¶

Quite las instrucciones assert y cualquier código condicionado al valor de __debug__. Aumente el nombre de archivo para los archivos compilados (bytecode) agregando .opt-1 antes de la extensión .pyc (consulte PEP 488). Véase también PYTHONOPTIMIZE.

Distinto en la versión 3.5: Modifique los nombres de archivo .pyc según PEP 488.

-OO¶

Haga -O y también deseche las docstrings. Aumente el nombre de archivo para los archivos compilados (bytecode) agregando .opt-2 antes de la extensión .pyc (consulte PEP 488).

Distinto en la versión 3.5: Modifique los nombres de archivo .pyc según PEP 488.

-P¶

No anteponga una ruta potencialmente insegura a sys.path:

• python -m module command line: No anteponga el directorio de trabajo actual.

• python script.py command line: No anteponga el directorio del script. Si es un enlace simbólico, resuelva los enlaces simbólicos.

• python -c code y python (REPL) command lines: No anteponga una cadena vacía, lo que significa el directorio de trabajo actual.

Consulte también la variable de entorno PYTHONSAFEPATH y las opciones -E y -I (aisladas).

Added in version 3.11.

-q¶

No muestres los mensajes de copyright y versión incluso en modo interactivo.

Added in version 3.2.

-R¶

Turn on hash randomization. This option only has an effect if the PYTHONHASHSEED environment variable is set to anything other than random, since hash randomization is enabled by default.

On previous versions of Python, this option turns on hash randomization, so that the __hash__() values of str and bytes objects are «salted» with an unpredictable random value. Although they remain constant within an individual Python process, they are not predictable between repeated invocations of Python.

Hash randomization is intended to provide protection against a denial-of-service caused by carefully chosen inputs that exploit the worst case performance of a dict construction, O(n²) complexity. See http://ocert.org/advisories/ocert-2011-003.html for details.

PYTHONHASHSEED le permite establecer un valor fijo para el secreto de inicialización hash.

Added in version 3.2.3.

Distinto en la versión 3.7: La opción ya no se omite.

-s¶

No agregue el user site-packages directory a sys.path.

See also PYTHONNOUSERSITE.

Ver también

PEP 370 – Directorio de paquetes de sitio por usuario

-S¶

Deshabilite la importación del módulo site y las manipulaciones dependientes del sitio de sys.path que conlleva. También deshabilite estas manipulaciones si site se importa explícitamente más tarde (llame a site.main() si desea que se activen).

-u¶

Forzar que las corrientes stdout y stderr no estén en búfer. Esta opción no tiene ningún efecto en la secuencia stdin.

Véase también PYTHONUNBUFFERED.

Distinto en la versión 3.7: La capa de texto de las secuencias stdout y stderr ahora no está en búfer.

-v¶

Imprime un mensaje cada vez que se inicialice un módulo, mostrando el lugar (nombre de archivo o módulo integrado) desde el que se carga. Cuando se le pasa dos veces (-vv), imprime un mensaje para cada archivo que se comprueba al buscar un módulo. También proporciona información sobre la limpieza del módulo en la salida.

Distinto en la versión 3.10: El módulo site informa las rutas específicas del sitio y los archivos .pth que se están procesando.

Véase también PYTHONVERBOSE.

-W arg¶

Control de advertencia. La maquinaria de advertencia de Python por defecto imprime mensajes de advertencia en sys.stderr.

La configuración más sencilla aplica una acción determinada incondicionalmente a todas las advertencias emitidas por un proceso (incluso aquellas que de otro modo se ignoran de forma predeterminada):

-Wdefault  # Warn once per call location
-Werror    # Convert to exceptions
-Walways   # Warn every time
-Wall      # Same as -Walways
-Wmodule   # Warn once per calling module
-Wonce     # Warn once per Python process
-Wignore   # Never warn

Los nombres de acción se pueden abreviar como se desee y el intérprete los resolverá con el nombre de acción adecuado. Por ejemplo, -Wi es lo mismo que -Wignore.

La forma completa del argumento es:

action:message:category:module:lineno

Los campos vacíos cuadran con todos los valores; los campos vacíos finales pueden omitirse. Por ejemplo, -W ignore::DeprecationWarning ignora todas las advertencias de DeprecationWarning.

El campo action es como se explicó anteriormente, pero solo se aplica a las advertencias que coinciden con los campos restantes.

El campo message debe coincidir con el mensaje de advertencia completo; esta coincidencia no distingue entre mayúsculas y minúsculas.

El campo category coincide con la categoría de advertencia (por ej. DeprecationWarning). Debe ser un nombre de clase; la coincidencia prueba si la categoría de advertencia real del mensaje es una subclase de la categoría de advertencia especificada.

El campo module coincide con el nombre de dominio completo del módulo; esta coincidencia distingue entre mayúsculas y minúsculas.

El campo lineno coincide con el número de línea, donde cero corresponde a todos los números de línea y, por lo tanto, es equivalente a número de línea omitido.

Se pueden dar varias opciones -W; cuando una advertencia coincide con más de una opción, se realiza la acción para la última opción de coincidencia. Las opciones invalidas -W son ignoradas (aunque se imprime un mensaje de advertencia sobre opciones no válidas cuando se emite la primera advertencia).

Las advertencias también se pueden controlar utilizando la variable de entorno PYTHONWARNINGS y desde un programa Python utilizando el módulo warnings. Por ejemplo, la función warnings.filterwarnings() puede ser usarse con una expresión regular en el mensaje de advertencia.

Consulte El filtro de advertencias y Descripción de los filtros de advertencia para obtener más detalles.

-x¶

Omita la primera línea de la fuente, permitiendo el uso de formas que no sean de Unix de #!cmd. Esto está destinado a un hackeo específico de DOS solamente.

-X¶

Reservado para varias opciones específicas de la implementación. CPython define actualmente los siguientes valores posibles:

• -X faulthandler para habilitar faulthandler. Véase PYTHONFAULTHANDLER para obtener más información.

  Added in version 3.3.

• -X showrefcount para generar el recuento total de referencias y el número de bloques de memoria utilizados cuando finalice el programa o después de cada instrucción en el intérprete interactivo. Esto sólo funciona en compilaciones de depuración.

  Added in version 3.4.

• -X tracemalloc para iniciar el seguimiento de las asignaciones de memoria de Python mediante el módulo tracemalloc. De forma predeterminada, solo el marco más reciente se almacena en un seguimiento de un seguimiento. Utilice -X tracemalloc=NFRAME para iniciar el seguimiento con un límite de rastreo de marcos NFRAME. Consulte el tracemalloc.start() y PYTHONTRACEMALLOC para obtener más información.

  Added in version 3.4.

• -X int_max_str_digits configura la limitación de longitud de conversión de cadena de tipo entero. Véase también PYTHONINTMAXSTRDIGITS.

  Added in version 3.11.

• -X importtime to show how long each import takes. It shows module name, cumulative time (including nested imports) and self time (excluding nested imports). Note that its output may be broken in multi-threaded application. Typical usage is python -X importtime -c 'import asyncio'.

  -X importtime=2 enables additional output that indicates when an imported module has already been loaded. In such cases, the string cached will be printed in both time columns.

  See also PYTHONPROFILEIMPORTTIME.

  Added in version 3.7.

  Distinto en la versión 3.14: Added -X importtime=2 to also trace imports of loaded modules, and reserved values other than 1 and 2 for future use.

• -X dev: enable Python Development Mode, introducing additional runtime checks that are too expensive to be enabled by default. See also PYTHONDEVMODE.

  Added in version 3.7.

• -X utf8 habilita el modo Python UTF-8. -X utf8=0 desactiva explícitamente el modo Python UTF-8 (incluso cuando al contrario se activaría automáticamente). Véase PYTHONUTF8.

  Added in version 3.7.

• -X pycache_prefix=PATH permite escribir archivos .pyc en un árbol paralelo enraizado en el directorio dado en lugar de en el árbol de código. Véase también PYTHONPYCACHEPREFIX.

  Added in version 3.8.

• -X warn_default_encoding emite un EncodingWarning cuando se usa la codificación predeterminada específica de la configuración regional para abrir archivos. Vea también PYTHONWARNDEFAULTENCODING.

  Added in version 3.10.

• -X no_debug_ranges deshabilita la inclusión de tablas que asignan información de ubicación adicional (línea final, desplazamiento de columna inicial y desplazamiento de columna final) a cada instrucción en los objetos de código. Esto es útil cuando se desean objetos de código más pequeños y archivos pyc, además de suprimir los indicadores de ubicación visuales adicionales cuando el intérprete muestra rastreos. Véase también PYTHONNODEBUGRANGES.

  Added in version 3.11.

• -X frozen_modules determines whether or not frozen modules are ignored by the import machinery. A value of on means they get imported and off means they are ignored. The default is on if this is an installed Python (the normal case). If it’s under development (running from the source tree) then the default is off. Note that the importlib_bootstrap and importlib_bootstrap_external frozen modules are always used, even if this flag is set to off. See also PYTHON_FROZEN_MODULES.

  Added in version 3.11.

• -X perf habilita el soporte para el perfilador perf de Linux. Cuando se proporciona esta opción, el perfilador perf podrá informar llamadas de Python. Esta opción sólo está disponible en algunas plataformas y no hará nada si no es compatible con el sistema actual. El valor predeterminado es «off». Consulte también PYTHONPERFSUPPORT y Soporte de Python para el perfilador perf de Linux.

  Added in version 3.12.

• -X perf_jit enables support for the Linux perf profiler with DWARF support. When this option is provided, the perf profiler will be able to report Python calls using DWARF information. This option is only available on some platforms and will do nothing if is not supported on the current system. The default value is «off». See also PYTHON_PERF_JIT_SUPPORT and Soporte de Python para el perfilador perf de Linux.

  Added in version 3.13.

• -X disable_remote_debug disables the remote debugging support as described in PEP 768. This includes both the functionality to schedule code for execution in another process and the functionality to receive code for execution in the current process.

  This option is only available on some platforms and will do nothing if is not supported on the current system. See also PYTHON_DISABLE_REMOTE_DEBUG and PEP 768.

  Added in version 3.14.

• -X cpu_count=n overrides os.cpu_count(), os.process_cpu_count(), and multiprocessing.cpu_count(). n must be greater than or equal to 1. This option may be useful for users who need to limit CPU resources of a container system. See also PYTHON_CPU_COUNT. If n is default, nothing is overridden.

  Added in version 3.13.

• -X presite=package.module specifies a module that should be imported before the site module is executed and before the __main__ module exists. Therefore, the imported module isn’t __main__. This can be used to execute code early during Python initialization. Python needs to be built in debug mode for this option to exist. See also PYTHON_PRESITE.

  Added in version 3.13.

• -X gil=0,1 forces the GIL to be disabled or enabled, respectively. Setting to 0 is only available in builds configured with --disable-gil. See also PYTHON_GIL and Free-threaded CPython.

  Added in version 3.13.

• -X thread_inherit_context=0,1 causes Thread to, by default, use a copy of context of the caller of Thread.start() when starting. Otherwise, threads will start with an empty context. If unset, the value of this option defaults to 1 on free-threaded builds and to 0 otherwise. See also PYTHON_THREAD_INHERIT_CONTEXT.

  Added in version 3.14.

• -X context_aware_warnings=0,1 causes the warnings.catch_warnings context manager to use a ContextVar to store warnings filter state. If unset, the value of this option defaults to 1 on free-threaded builds and to 0 otherwise. See also PYTHON_CONTEXT_AWARE_WARNINGS.

  Added in version 3.14.

• -X tlbc=0,1 enables (1, the default) or disables (0) thread-local bytecode in builds configured with --disable-gil. When disabled, this also disables the specializing interpreter. See also PYTHON_TLBC.

  Added in version 3.14.

También permite pasar valores arbitrarios y recuperarlos a través del diccionario sys._xoptions.

Added in version 3.2.

Distinto en la versión 3.9: Removed the -X showalloccount option.

Distinto en la versión 3.10: Removed the -X oldparser option.

1.1.4. Controlling color¶

The Python interpreter is configured by default to use colors to highlight output in certain situations such as when displaying tracebacks. This behavior can be controlled by setting different environment variables.

Setting the environment variable TERM to dumb will disable color.

If the FORCE_COLOR environment variable is set, then color will be enabled regardless of the value of TERM. This is useful on CI systems which aren’t terminals but can still display ANSI escape sequences.

If the NO_COLOR environment variable is set, Python will disable all color in the output. This takes precedence over FORCE_COLOR.

All these environment variables are used also by other tools to control color output. To control the color output only in the Python interpreter, the PYTHON_COLORS environment variable can be used. This variable takes precedence over NO_COLOR, which in turn takes precedence over FORCE_COLOR.

1.2.1. Variables de modo de depuración¶

PYTHONDUMPREFS¶

Si se establece, Python volcará objetos y recuentos de referencias aún vivos después de apagar el intérprete.

Needs Python configured with the --with-trace-refs build option.

PYTHONDUMPREFSFILE¶

If set, Python will dump objects and reference counts still alive after shutting down the interpreter into a file under the path given as the value to this environment variable.

Needs Python configured with the --with-trace-refs build option.

Added in version 3.11.

PYTHON_PRESITE¶

If this variable is set to a module, that module will be imported early in the interpreter lifecycle, before the site module is executed, and before the __main__ module is created. Therefore, the imported module is not treated as __main__.

This can be used to execute code early during Python initialization.

To import a submodule, use package.module as the value, like in an import statement.

See also the -X presite command-line option, which takes precedence over this variable.

Needs Python configured with the --with-pydebug build option.

Added in version 3.13.