Documentación offline Python 3.14

"ftplib" --- FTP protocol client

3.14 Ver versión oficial en línea Licencia PSF-2.0Descargado el 2026-08-02

En esta página

"ftplib" --- FTP protocol client#

Código fuente Lib/ftplib.py

======================================================================

Este módulo define la clase "FTP" y algunos elementos relacionados. La clase "FTP" implementa el lado cliente del protocolo FTP. Puede usar esto para escribir programas de Python que realicen una variedad de trabajos FTP automatizados, como duplicar otros servidores FTP. También es utilizado por el módulo "urllib.request" para manejar URL que usan FTP. Para más información sobre FTP (File Transfer Protocol), ver internet RFC 959.

La codificación predeterminada es UTF-8, siguiendo RFC 2640.

Availability: not WASI.

This module does not work or is not available on WebAssembly. See Plataformas WebAssembly for more information.

Here's a sample session using the "ftplib" module:

from ftplib import FTP ftp = FTP('ftp.us.debian.org') # connect to host, default port ftp.login() # user anonymous, passwd anonymous@ '230 Login successful.' ftp.cwd('debian') # change into "debian" directory '250 Directory successfully changed.' ftp.retrlines('LIST') # list directory contents -rw-rw-r-- 1 1176 1176 1063 Jun 15 10:18 README ... drwxr-sr-x 5 1176 1176 4096 Dec 19 2000 pool drwxr-sr-x 4 1176 1176 4096 Nov 17 2008 project drwxr-xr-x 3 1176 1176 4096 Oct 10 2012 tools '226 Directory send OK.' with open('README', 'wb') as fp: ftp.retrbinary('RETR README', fp.write) '226 Transfer complete.' ftp.quit() '221 Goodbye.'

Reference#

FTP objects#

class ftplib.FTP(host='', user='', passwd='', acct='', timeout=None, source_address=None, *, encoding='utf-8')

Return a new instance of the "FTP" class.

Parámetros: * host (str) -- The hostname to connect to. If given, "connect(host)" is implicitly called by the constructor.

  * **user** (*str*) -- The username to log in with (default:
    "'anonymous'"). If given, "login(host, passwd, acct)" is
    implicitly called by the constructor.

  * **passwd** (*str*) -- The password to use when logging in. If
    not given, and if *passwd* is the empty string or ""-"", a
    password will be automatically generated.

  * **acct** (*str*) -- Account information to be used for the
    "ACCT" FTP command. Few systems implement this. See RFC-959
    for more details.

  * **timeout** (*float** | **None*) -- A timeout in seconds for
    blocking operations like "connect()" (default: the global
    default timeout setting).

  * **source_address** (*tuple** | **None*) -- A 2-tuple "(host,
    port)" for the socket to bind to as its source address before
    connecting.

  * **encoding** (*str*) -- The encoding for directories and
    filenames (default: "'utf-8'").

La clase "FTP" admite la instrucción "with", por ejemplo:

from ftplib import FTP with FTP("ftp1.at.proftpd.org") as ftp: ... ftp.login() ... ftp.dir() ... '230 Anonymous login ok, restrictions apply.' dr-xr-xr-x 9 ftp ftp 154 May 6 10:43 . dr-xr-xr-x 9 ftp ftp 154 May 6 10:43 .. dr-xr-xr-x 5 ftp ftp 4096 May 6 10:43 CentOS dr-xr-xr-x 3 ftp ftp 18 Jul 10 2008 Fedora

Distinto en la versión 3.2: Se agregó compatibilidad con la instrucción "with".

Distinto en la versión 3.3: Se agregó el parámetro source_address.

Distinto en la versión 3.9: Si el parámetro timeout se establece en cero, lanzará un "ValueError" para evitar la creación de un socket sin bloqueo. Se agregó el parámetro encoding, y el valor predeterminado se cambió de Latin-1 a UTF-8 para seguir RFC 2640.

Several "FTP" methods are available in two flavors: one for handling text files and another for binary files. The methods are named for the command which is used followed by "lines" for the text version or "binary" for the binary version.

Las instancias de "FTP" tienen los siguientes métodos:

set_debuglevel(level)

  Set the instance's debugging level as an "int". This controls
  the amount of debugging output printed. The debug levels are:

  * "0" (default): No debug output.

  * "1": Produce a moderate amount of debug output, generally a
    single line per request.

  * "2" or higher: Produce the maximum amount of debugging output,
    logging each line sent and received on the control connection.

connect(host='', port=0, timeout=None, source_address=None)

  Connect to the given host and port. This function should be
  called only once for each instance; it should not be called if a
  *host* argument was given when the "FTP" instance was created.
  All other "FTP" methods can only be called after a connection
  has successfully been made.

  Parámetros:
     * **host** (*str*) -- The host to connect to.

     * **port** (*int*) -- The TCP port to connect to (default:
       "21", as specified by the FTP protocol specification). It
       is rarely needed to specify a different port number.

     * **timeout** (*float** | **None*) -- A timeout in seconds
       for the connection attempt (default: the global default
       timeout setting).

     * **source_address** (*tuple** | **None*) -- A 2-tuple
       "(host, port)" for the socket to bind to as its source
       address before connecting.

  Lanza un evento auditor "ftplib.connect" con los argumentos
  "self", "host", "port".

  Distinto en la versión 3.3: Se agregó el parámetro
  *source_address*.

getwelcome()

  Retornar el mensaje de bienvenida enviado por el servidor como
  respuesta a la conexión inicial. (Este mensaje a veces contiene
  renuncias de responsabilidad o información de ayuda que puede
  ser relevante para el usuario.)

login(user='anonymous', passwd='', acct='')

  Log on to the connected FTP server. This function should be
  called only once for each instance, after a connection has been
  established; it should not be called if the *host* and *user*
  arguments were given when the "FTP" instance was created. Most
  FTP commands are only allowed after the client has logged in.

  Parámetros:
     * **user** (*str*) -- The username to log in with (default:
       "'anonymous'").

     * **passwd** (*str*) -- The password to use when logging in.
       If not given, and if *passwd* is the empty string or ""-"",
       a password will be automatically generated.

     * **acct** (*str*) -- Account information to be used for the
       "ACCT" FTP command. Few systems implement this. See RFC-959
       for more details.

abort()

  Anula una transferencia de archivo que está en progreso. Usarlo
  no siempre funciona, pero vale la pena intentarlo.

sendcmd(cmd)

  Envía una cadena de comando simple al servidor y retorna la
  cadena de caracteres de respuesta.

  Genera un evento auditor "ftplib.sendcmd" con los argumentos
  "self", "cmd".

voidcmd(cmd)

  Send a simple command string to the server and handle the
  response.  Return the response string if the response code
  corresponds to success (codes in the range 200--299).  Raise
  "error_reply" otherwise.

  Genera un evento auditor "ftplib.sendcmd" con los argumentos
  "self", "cmd".

retrbinary(cmd, callback, blocksize=8192, rest=None)

  Retrieve a file in binary transfer mode.

  Parámetros:
     * **cmd** (*str*) -- An appropriate "RETR" command: ""RETR
       *filename*"".

     * **callback** (*callable*) -- A single parameter callable
       that is called for each block of data received, with its
       single argument being the data as "bytes".

     * **blocksize** (*int*) -- The maximum chunk size to read on
       the low-level "socket" object created to do the actual
       transfer. This also corresponds to the largest size of data
       that will be passed to *callback*. Defaults to "8192".

     * **rest** (*int*) -- A "REST" command to be sent to the
       server. See the documentation for the *rest* parameter of
       the "transfercmd()" method.

retrlines(cmd, callback=None)

  Retrieve a file or directory listing in the encoding specified
  by the *encoding* parameter at initialization. *cmd* should be
  an appropriate "RETR" command (see "retrbinary()") or a command
  such as "LIST" or "NLST" (usually just the string "'LIST'").
  "LIST" retrieves a list of files and information about those
  files. "NLST" retrieves a list of file names. The *callback*
  function is called for each line with a string argument
  containing the line with the trailing CRLF stripped.  The
  default *callback* prints the line to "sys.stdout".

set_pasv(val)

  Habilita el modo pasivo si *val* es verdadero, de lo contrario
  lo inhabilita. El modo pasivo es el valor predeterminado.

storbinary(cmd, fp, blocksize=8192, callback=None, rest=None)

  Store a file in binary transfer mode.

  Parámetros:
     * **cmd** (*str*) -- An appropriate "STOR" command: ""STOR
       *filename*"".

     * **fp** (*file object*) -- A file object (opened in binary
       mode) which is read until EOF, using its "read()" method in
       blocks of size *blocksize* to provide the data to be
       stored.

     * **blocksize** (*int*) -- The read block size. Defaults to
       "8192".

     * **callback** (*callable*) -- A single parameter callable
       that is called for each block of data sent, with its single
       argument being the data as "bytes".

     * **rest** (*int*) -- A "REST" command to be sent to the
       server. See the documentation for the *rest* parameter of
       the "transfercmd()" method.

  Distinto en la versión 3.2: The *rest* parameter was added.

storlines(cmd, fp, callback=None)

  Almacena un archivo en modo de línea. *cmd* debe ser un comando
  "STOR" apropiado (ver "storbinary()"). Las líneas se leen hasta
  EOF del *file object* *fp* (abierto en modo binario) usando su
  método "readline()" para proporcionar los datos que se
  almacenarán. *callback* es un parámetro único opcional que se
  puede llamar en cada línea después de su envío.

transfercmd(cmd, rest=None)

  Inicia una transferencia sobre la conexión de datos.  Si la
  transferencia es activa, envía un comando "EPRT" o  "PORT" y el
  comando de transferencia especificado por *cmd*, y acepta la
  conexión. Si el servidor es pasivo, envía un comando "EPSV" o
  "PASV", lo conecta, e inicia el comando de transferencia. De
  cualquier manera, retorna el socket para la conexión.

  Si se proporciona *rest* opcional, se envía un comando "REST" al
  servidor, pasando *rest* como argumento. *rest* suele ser un
  desplazamiento de bytes en el archivo solicitado, que le indica
  al servidor que reinicie el envío de los bytes del archivo en el
  desplazamiento solicitado, omitiendo los bytes iniciales. Sin
  embargo, tenga en cuenta que el método "transfercmd()" convierte
  *rest* en una cadena de caracteres con el parámetro *encoding*
  especificado en la inicialización, pero no se realiza ninguna
  comprobación del contenido de la cadena de caracteres. Si el
  servidor no reconoce el comando "REST", se lanzará una excepción
  "error_reply". Si esto sucede, simplemente llame a
  "transfercmd()" sin un argumento *rest*.

ntransfercmd(cmd, rest=None)

  Como "transfercmd()", pero retorna una tupla de conexión de
  datos y el tamaño esperado de los datos. Si el tamaño esperado
  no se pudo computar, retornará "None" como tal. *cmd* y *rest*
  significan lo mismo que en "transfercmd()".

mlsd(path='', facts=[])

  Enumera un directorio en un formato estandarizado usando el
  comando "MLSD" (**RFC 3659**). Si se omite *path*, se asume el
  directorio actual. *facts* es una lista de cadenas de caracteres
  que representan el tipo de información deseada (por ejemplo,
  "["type", "size", "perm"]"). Retorna un objeto generador que
  produce una tupla de dos elementos por cada archivo encontrado
  en la ruta. El primer elemento es el nombre del archivo, el
  segundo es un diccionario que contiene datos sobre el nombre del
  archivo. El contenido de este diccionario puede estar limitado
  por el argumento *facts*, pero no se garantiza que el servidor
  retorne todos los datos solicitados.

  Added in version 3.3.

nlst(argument[, ...])

  Retorna una lista de nombres de archivos tal como los retorna el
  comando "NLST". El *argument* opcional es un directorio para
  listar (el predeterminado es el directorio del servidor actual).
  Se pueden usar varios argumentos para pasar opciones no estándar
  al comando "NLST".

  Nota:

    Si tu servidor admite el comando, "mlsd()" ofrece una API
    mejor.

dir(argument[, ...])

  Produce a directory listing as returned by the "LIST" command,
  printing it to standard output.  The optional *argument* is a
  directory to list (default is the current server directory).
  Multiple arguments can be used to pass non-standard options to
  the "LIST" command.  If the last argument is a function, it is
  used as a *callback* function as for "retrlines()"; the default
  prints to "sys.stdout".  This method returns "None".

  Nota:

    Si tu servidor admite el comando, "mlsd()" ofrece una API
    mejor.

rename(fromname, toname)

  Asigna un nombre nuevo al archivo en el servidor desde
  *fromname* a *toname*.

delete(filename)

  Remueve el archivo nombrado *filename* del servidor.  De ser
  exitoso, retorna el texto de la respuesta, de lo contrario,
  lanza "error_perm" sobre errores de permiso o "error_reply"
  sobre otros errores.

cwd(pathname)

  Configura el directorio actual en el servidor.

mkd(pathname)

  Crea un nuevo directorio en el servidor.

pwd()

  Retorna el nombre de ruta del directorio actual en el servidor.

rmd(dirname)

  Elimina el directorio en el servidor llamado *dirname*.

size(filename)

  Solicita el tamaño del archivo llamado *filename* en el
  servidor.  De ser exitoso, se retorna el tamaño del archivo como
  un entero, de lo contrario retorna "None". Nótese que el comando
  "SIZE" no está estandarizado, pero es admitido por muchas
  implementaciones comunes de servidor.

quit()

  Envía un comando "QUIT" al servidor y cierra la conexión. Esta
  es la forma "políticamente correcta" de cerrar una conexión,
  pero puede lanzar una excepción si el servidor responde con un
  error al comando "QUIT". Esto implica una llamada al método
  "close()" que hace inútil la instancia de "FTP" para llamadas
  posteriores (véase más adelante).

close()

  Cierra la conexión de forma unilateral. Esto no debería
  aplicarse a una conexión ya cerrada, como luego de una llamada
  exitosa a "quit()". Después de esta llamada, la instancia "FTP"
  ya no debería utilizarse (luego de una llamada a "close()" o
  "quit()" no puedes abrir nuevamente la conexión emitiendo otro
  método "login()".

FTP_TLS objects#

class ftplib.FTP_TLS(host='', user='', passwd='', acct='', *, context=None, timeout=None, source_address=None, encoding='utf-8')

An "FTP" subclass which adds TLS support to FTP as described in RFC 4217. Connect to port 21 implicitly securing the FTP control connection before authenticating.

Nota:

 The user must explicitly secure the data connection by calling
 the "prot_p()" method.

Parámetros: * host (str) -- The hostname to connect to. If given, "connect(host)" is implicitly called by the constructor.

  * **user** (*str*) -- The username to log in with (default:
    "'anonymous'"). If given, "login(host, passwd, acct)" is
    implicitly called by the constructor.

  * **passwd** (*str*) -- The password to use when logging in. If
    not given, and if *passwd* is the empty string or ""-"", a
    password will be automatically generated.

  * **acct** (*str*) -- Account information to be used for the
    "ACCT" FTP command. Few systems implement this. See RFC-959
    for more details.

  * **context** ("ssl.SSLContext") -- An SSL context object which
    allows bundling SSL configuration options, certificates and
    private keys into a single, potentially long-lived, structure.
    Please read Consideraciones de seguridad for best practices.

  * **timeout** (*float** | **None*) -- A timeout in seconds for
    blocking operations like "connect()" (default: the global
    default timeout setting).

  * **source_address** (*tuple** | **None*) -- A 2-tuple "(host,
    port)" for the socket to bind to as its source address before
    connecting.

  * **encoding** (*str*) -- The encoding for directories and
    filenames (default: "'utf-8'").

Added in version 3.2.

Distinto en la versión 3.3: Added the source_address parameter.

Distinto en la versión 3.4: La clase ahora admite el chequeo del nombre con "ssl.SSLContext.check_hostname" y Server Name Indication (véase "ssl.HAS_SNI").

Distinto en la versión 3.9: Si el parámetro timeout se establece en cero, lanzará un "ValueError" para evitar la creación de un socket sin bloqueo. Se agregó el parámetro encoding, y el valor predeterminado se cambió de Latin-1 a UTF-8 para seguir RFC 2640.

Distinto en la versión 3.12: Se han eliminado los parámetros obsoletos keyfile y certfile.

Aquí hay una sesión de ejemplo que usa la clase "FTP_TLS":

  >>> ftps = FTP_TLS('ftp.pureftpd.org')
  >>> ftps.login()
  '230 Anonymous user logged in'
  >>> ftps.prot_p()
  '200 Data protection level set to "private"'
  >>> ftps.nlst()
  ['6jack', 'OpenBSD', 'antilink', 'blogbench', 'bsdcam', 'clockspeed', 'djbdns-jedi', 'docs', 'eaccelerator-jedi', 'favicon.ico', 'francotone', 'fugu', 'ignore', 'libpuzzle', 'metalog', 'minidentd', 'misc', 'mysql-udf-global-user-variables', 'php-jenkins-hash', 'php-skein-hash', 'php-webdav', 'phpaudit', 'phpbench', 'pincaster', 'ping', 'posto', 'pub', 'public', 'public_keys', 'pure-ftpd', 'qscan', 'qtc', 'sharedance', 'skycache', 'sound', 'tmp', 'ucarp']

"FTP_TLS" class inherits from "FTP", defining these additional methods and attributes:

ssl_version

  La versión SSL para usar (toma como predeterminado
  "ssl.PROTOCOL_SSLv23").

auth()

  Establece una conexión de control segura usando TLS o SSL,
  dependiendo de qué esté especificado en el atributo
  "ssl_version".

  Distinto en la versión 3.4: El método ahora admite el chequeo
  del nombre con "ssl.SSLContext.check_hostname" y *Server Name
  Indication* (véase "ssl.HAS_SNI").

ccc()

  Revierte el canal de control a texto plano. Esto puede ser útil
  para aprovechar cortafuegos que saben manejar NAT con FTP no-
  seguro sin abrir puertos fijos.

  Added in version 3.3.

prot_p()

  Configura conexión de datos segura.

prot_c()

  Configura la conexión de datos de tipo texto común.

Module variables#

exception ftplib.error_reply

Se lanza una excepción cuando una respuesta inesperada se recibe del servidor.

exception ftplib.error_temp

Se genera una excepción cuando se recibe un código de error que refiere a un error temporal (códigos de respuesta en el rango 400-499).

exception ftplib.error_perm

Se lanza una excepción cuando se recibe un código de error que refiere a un error permanente (códigos de respuesta en el rango 500 --599).

exception ftplib.error_proto

Se lanza una excepción cuando se recibe una respuesta del servidor que no coincide con las especificaciones de respuesta del protocolo de transferencia de archivos (FTP), es decir, que comienza con un dígito en el rango 1--5.

ftplib.all_errors

El conjunto de todas las excepciones (como una tupla) que los métodos de instancias "FTP" pueden lanzar como resultado de problemas con la conexión FTP (a diferencia de los errores de programación hechos por el autor de la llamada). Este conjunto incluye las cuatro excepciones enumeradas anteriormente, como también "OSError" y "EOFError".

Ver también:

Módulo "netrc" Analizador para el formato de archivo ".netrc". El archivo ".netrc" suele ser utilizado por clientes FTP para cargar la información de autenticación de usuario antes de solicitarlo al usuario.