---
title: "File: list, transfer and delete files"
description: "List, download, upload, read, write, delete and rename the files and directories of a robot controller with robot.File. Brand support table, C# and Python examples."
---

# File: list, transfer and delete files

`robot.File` lists, reads, writes, deletes and renames the files and the directories of a robot controller, and transfers them to and from the PC. The paths use the native syntax of the controller. The result type is the same on every brand. The methods that you can call depend on the brand: see the table below.

## Prerequisites

- A connected `RobotController`. See [Connect to your robot](/robotics/documentation/connect).
- The license of the brand of the controller, or the 30 day trial. See [Licensing](/robotics/documentation/license).
- A path in the native syntax of the controller, for example `md:/MAIN.TP` on a Fanuc controller. `RemoteFileInfo.FullPath` gives a path that you can give to the other methods.
- Upload, write, delete and rename change the controller. A file that you upload or write replaces the file of the same path.

## Brand support

Each cell gives the protocol that the method uses on this brand, in the default order. The page [Routing](/robotics/documentation/routing) explains how the library chooses it. The table is generated from the route data of the library. (manual) marks a route that you enable yourself. "n of m" is the number of methods of the service that have a route on this brand.

Routes of each method in the default order. The first route is used, the next ones are fallbacks. (manual) marks a route that you enable yourself.

| Method | Fanuc | Yaskawa | Universal Robots | ABB | Stäubli |
| --- | --- | --- | --- | --- | --- |
| File.List | FTP, CGTP (Cgtp) | FTP, High Speed Ethernet Server, HTTP | SFTP | Robot Web Services | Files |
| File.Download | FTP | FTP, High Speed Ethernet Server, HTTP | SFTP | Robot Web Services | Files |
| File.ReadBytes | FTP | FTP, High Speed Ethernet Server, HTTP | SFTP | Robot Web Services | Files |
| File.ReadText | FTP, CGTP (Cgtp) | FTP, High Speed Ethernet Server, HTTP | SFTP | Robot Web Services | Files |
| File.Upload | FTP | FTP, High Speed Ethernet Server | SFTP | Robot Web Services | Files |
| File.WriteBytes | FTP | FTP, High Speed Ethernet Server | SFTP | Robot Web Services | Files |
| File.WriteText | FTP | FTP, High Speed Ethernet Server | SFTP | Robot Web Services | Files |
| File.Delete | FTP | FTP, High Speed Ethernet Server | SFTP | Robot Web Services | Files |
| File.Exists | FTP | FTP | SFTP | Robot Web Services | Files |
| File.Rename | FTP | Not available | SFTP | Robot Web Services | Files |
| File.CreateDirectory | FTP | Not available | SFTP | Robot Web Services | Files |
| File.DeleteDirectory | FTP | Not available | SFTP | Robot Web Services | Files |
| File.ReadBytesWithProgress | FTP | FTP, High Speed Ethernet Server, HTTP | SFTP | Robot Web Services | Files |
| File.WriteBytesWithProgress | FTP | FTP, High Speed Ethernet Server | SFTP | Robot Web Services | Files |
| File | **14 of 14** | **11 of 14** | **14 of 14** | **14 of 14** | **14 of 14** |

A brand that has no route for a method throws `FeatureNotSupportedException` (see [Errors](/robotics/documentation/errors)). Ask `robot.File.IsAvailable(FileFeature.CreateDirectory)` before the call.

## Example

### List a directory

`List` returns the files and the directories of a directory. `IsDirectory` is true for a directory, and `Size` is 0 for a directory or when the controller does not give it. Check `HasModificationDate` before you use `ModificationDate`.

**C# : FileList**
```csharp
using UnderAutomation.Robotics.Controllers;

public class FileList
{
    static void Main()
    {
        RobotController robot = new RobotController();
        robot.Connect(RobotConnectionParameters.Create("fanuc", "192.168.0.1"));

        /**/
        // Native syntax of the controller. "md:" is the memory device of a Fanuc controller.
        foreach (RemoteFileInfo file in robot.File.List("md:/"))
            Console.WriteLine($"{(file.IsDirectory ? "[dir]" : file.Size + " bytes")} {file.FullPath}");
        /**/

        robot.Disconnect();
    }
}
```

**Python : FileList**
```python
from underautomation.robotics.controllers.robot_controller import RobotController
from underautomation.robotics.controllers.robot_connection_parameters import RobotConnectionParameters

robot = RobotController()
robot.connect(RobotConnectionParameters.create("fanuc", "192.168.0.1", ""))

##
# Native syntax of the controller. "md:" is the memory device of a Fanuc controller.
for file in robot.file.list("md:/"):
    size = "[dir]" if file.is_directory else f"{file.size} bytes"
    print(f"{size} {file.full_path}")
##

robot.disconnect()
```

### Download a file

`Download` writes a file of the controller to a local file, and replaces it when it exists. `ReadBytes` keeps the content in memory.

**C# : FileDownload**
```csharp
using UnderAutomation.Robotics.Controllers;

public class FileDownload
{
    static void Main()
    {
        RobotController robot = new RobotController();
        robot.Connect(RobotConnectionParameters.Create("fanuc", "192.168.0.1"));

        /**/
        robot.File.Download("md:/MAIN.TP", @"C:\Temp\MAIN.TP");

        // Or keep the content in memory
        byte[] content = robot.File.ReadBytes("md:/MAIN.TP");
        /**/

        robot.Disconnect();
    }
}
```

**Python : FileDownload**
```python
from underautomation.robotics.controllers.robot_controller import RobotController
from underautomation.robotics.controllers.robot_connection_parameters import RobotConnectionParameters

robot = RobotController()
robot.connect(RobotConnectionParameters.create("fanuc", "192.168.0.1", ""))

##
robot.file.download("md:/MAIN.TP", r"C:\Temp\MAIN.TP")

# Or keep the content in memory
content = robot.file.read_bytes("md:/MAIN.TP")
##

robot.disconnect()
```

### Upload a file

`Upload` writes a local file on the controller, and replaces the file of the controller when it exists. `WriteBytes` writes the content that you have in memory.

**C# : FileUpload**
```csharp
using UnderAutomation.Robotics.Controllers;

public class FileUpload
{
    static void Main()
    {
        RobotController robot = new RobotController();
        robot.Connect(RobotConnectionParameters.Create("fanuc", "192.168.0.1"));

        /**/
        // Replaces the file when it exists
        robot.File.Upload(@"C:\Temp\MAIN.TP", "md:/MAIN.TP");
        /**/

        robot.Disconnect();
    }
}
```

**Python : FileUpload**
```python
from underautomation.robotics.controllers.robot_controller import RobotController
from underautomation.robotics.controllers.robot_connection_parameters import RobotConnectionParameters

robot = RobotController()
robot.connect(RobotConnectionParameters.create("fanuc", "192.168.0.1", ""))

##
# Replaces the file when it exists
robot.file.upload(r"C:\Temp\MAIN.TP", "md:/MAIN.TP")
##

robot.disconnect()
```

### Read and write a text file

`WriteText` and `ReadText` handle a file as text. `Exists` returns true when a file or a directory exists on the controller. `Delete` deletes a file.

**C# : FileText**
```csharp
using UnderAutomation.Robotics.Controllers;

public class FileText
{
    static void Main()
    {
        RobotController robot = new RobotController();
        robot.Connect(RobotConnectionParameters.Create("fanuc", "192.168.0.1"));

        /**/
        robot.File.WriteText("md:/NOTES.TXT", "Cell 3");

        if (robot.File.Exists("md:/NOTES.TXT"))
        {
            Console.WriteLine(robot.File.ReadText("md:/NOTES.TXT"));
            robot.File.Delete("md:/NOTES.TXT");
        }
        /**/

        robot.Disconnect();
    }
}
```

**Python : FileText**
```python
from underautomation.robotics.controllers.robot_controller import RobotController
from underautomation.robotics.controllers.robot_connection_parameters import RobotConnectionParameters

robot = RobotController()
robot.connect(RobotConnectionParameters.create("fanuc", "192.168.0.1", ""))

##
robot.file.write_text("md:/NOTES.TXT", "Cell 3")

if robot.file.exists("md:/NOTES.TXT"):
    print(robot.file.read_text("md:/NOTES.TXT"))
    robot.file.delete("md:/NOTES.TXT")
##

robot.disconnect()
```

### Create, rename and delete directories

`CreateDirectory` and `DeleteDirectory` create and delete a directory. `Rename` renames or moves a file. A brand can have no route for some of these methods: ask `IsAvailable` first.

**C# : FileDirectory**
```csharp
using UnderAutomation.Robotics.Controllers;

public class FileDirectory
{
    static void Main()
    {
        RobotController robot = new RobotController();
        robot.Connect(RobotConnectionParameters.Create("fanuc", "192.168.0.1"));

        /**/
        // Not supported by every brand: ask first
        if (robot.File.IsAvailable(FileFeature.CreateDirectory))
        {
            robot.File.CreateDirectory("md:/backup");
            robot.File.Rename("md:/MAIN.TP", "md:/backup/MAIN.TP");
            robot.File.DeleteDirectory("md:/backup");
        }
        /**/

        robot.Disconnect();
    }
}
```

**Python : FileDirectory**
```python
from underautomation.robotics.controllers.robot_controller import RobotController
from underautomation.robotics.controllers.robot_connection_parameters import RobotConnectionParameters
from underautomation.robotics.controllers.file_feature import FileFeature

robot = RobotController()
robot.connect(RobotConnectionParameters.create("fanuc", "192.168.0.1", ""))

##
# Not supported by every brand: ask first
if robot.file.is_available(FileFeature.CreateDirectory):
    robot.file.create_directory("md:/backup")
    robot.file.rename("md:/MAIN.TP", "md:/backup/MAIN.TP")
    robot.file.delete_directory("md:/backup")
##

robot.disconnect()
```

### Follow a transfer

`ReadBytesWithProgress` and `WriteBytesWithProgress` do the same as `ReadBytes` and `WriteBytes`, with a progress callback and a cancellation. The callback receives the bytes transferred and the size of the file, or -1 when the size is not known yet. It is called on the thread of the transfer. The routes that have a progress call it during the transfer, the other routes only once at the end. The calls never go back, and the last one gives the size twice. A cancelled transfer throws `OperationCanceledException`. The cancellation is checked before the transfer, and during the transfer by the routes that have a progress: the transfer stops at the next block, and a file that you write can then be incomplete.

These two methods are not in the .NET Framework 3.5 build. The Python package has no wrapper for them: in Python, use `read_bytes` and `write_bytes`.

**C# : FileProgress**
```csharp
using UnderAutomation.Robotics.Controllers;

public class FileProgress
{
    static void Main()
    {
        RobotController robot = new RobotController();
        robot.Connect(RobotConnectionParameters.Create("fanuc", "192.168.0.1"));

        /**/
        using CancellationTokenSource cancellation = new CancellationTokenSource();

        // Bytes received and size of the file, -1 when the size is not known yet
        byte[] content = robot.File.ReadBytesWithProgress(
            "md:/MAIN.TP",
            (done, total) => Console.WriteLine($"{done} / {total}"),
            cancellation.Token);
        /**/

        robot.Disconnect();
    }
}
```

## Reference

In Python, the names are in snake_case: `robot.file.list("md:/")`, `robot.file.read_bytes(...)`, `robot.file.create_directory(...)`, `robot.file.is_available(...)`. The enum members keep their names. `read_bytes` returns a list of integers.

### Methods of IFileService

**Members of Controllers.IFileService**
```csharp
public interface IFileService {
    // Creates a directory on the controller
    void CreateDirectory(string remotePath)

    // Deletes a file of the controller
    void Delete(string remotePath)

    // Deletes a directory of the controller
    void DeleteDirectory(string remotePath)

    // Downloads a file of the controller to a local file
    void Download(string remotePath, string localPath)

    // Returns true when a file or a directory exists on the controller
    bool Exists(string remotePath)

    // Returns true when the method can be called on the connected controller.
    // The answer depends on the brand, on the routing settings and on the protocols that answered at the connection, not on the state of the controller.
    bool IsAvailable(FileFeature feature)

    // Lists the files and directories of a directory
    RemoteFileInfo[] List(string directory)

    // Reads the content of a file of the controller
    byte[] ReadBytes(string remotePath)

    // Reads the content of a text file of the controller
    string ReadText(string remotePath)

    // Renames or moves a file of the controller
    void Rename(string fromPath, string toPath)

    // Uploads a local file to the controller
    void Upload(string localPath, string remotePath)

    // Writes the content of a file of the controller
    void WriteBytes(string remotePath, byte[] data)

    // Writes the content of a text file of the controller
    void WriteText(string remotePath, string text)
}
```

Two methods are not in the .NET Framework 3.5 build, so the table above does not show them, and they have no Python wrapper:

- `byte[] ReadBytesWithProgress(string remotePath, Action<long, long> progress, CancellationToken cancellationToken)`: reads the content of a file. `progress` receives the bytes received and the size of the file, and can be null.
- `void WriteBytesWithProgress(string remotePath, byte[] data, Action<long, long> progress, CancellationToken cancellationToken)`: writes the content of a file, replaced when it exists. `progress` receives the bytes sent and the size of the data, and can be null.

### RemoteFileInfo

**Members of Controllers.RemoteFileInfo**
```csharp
public sealed class RemoteFileInfo {
    // Creates a file description with the default value of each property
    public RemoteFileInfo()

    // Full path, in the native syntax of the controller. It can be given to the other methods of the file service.
    public string FullPath { get; set; }

    // True when the controller gives the date of the last modification
    public bool HasModificationDate { get; set; }

    // True for a directory
    public bool IsDirectory { get; set; }

    // Date of the last modification, in the time of the controller. Valid only when <xref href="UnderAutomation.Robotics.Controllers.RemoteFileInfo.HasModificationDate" data-throw-if-not-resolved="false"></xref> is true.
    public DateTime ModificationDate { get; set; }

    // Name of the file or directory, without its directory
    public string Name { get; set; }

    // Object of the brand SDK this file comes from. Null when there is none.
    public object Native { get; set; }

    // Size in bytes. 0 for a directory or when the controller does not give it.
    public long Size { get; set; }

    public override string ToString()
}
```

A text and an array are empty when there is no value, never null. The result is a new object at each call.

### Errors

The page [Errors](/robotics/documentation/errors) explains each exception and how to avoid it.

- `FeatureNotSupportedException`: the brand has no route for the method.
- `RouteUnavailableException`: the method has routes, but none of them can be used, for example because the protocol did not answer at the connection.
- `ControllerRefusedException`: the controller received the command and refused it.
- `RobotControllerException`: the route failed. Its inner exception is the exception of the brand SDK.
- `ArgumentException`: an invalid argument.
- `OperationCanceledException`: the transfer of `ReadBytesWithProgress` or `WriteBytesWithProgress` was cancelled.

`IsAvailable` only throws `ArgumentOutOfRangeException`, for a value that is not in the enum.

## What to read next

- [Transfer files to and from a robot controller](/robotics/documentation/how-to-transfer-files): the same transfer on each brand, with the paths of each brand.
- [Program](/robotics/documentation/program): list and start the programs that you transferred.
- [Alarm](/robotics/documentation/alarm): read the alarm history of the controller.
- [Errors](/robotics/documentation/errors): catch the exceptions of the common API.