How to Copy Files with Ansible

Paul Hill

April 2, 2024 • 9 min read

    Ansible is a valuable automation tool that enables IT professionals to manage infrastructure more consistently and efficiently. One of the key features of Ansible is its copy module, which is straightforward yet powerful, allowing for the copying of files from local to remote systems. This module is not just about moving files around; it’s an essential part of automating routine tasks, deploying configurations, and ensuring that your environments are set up exactly as you need them, without manual intervention.

    If you want to take your Ansible skills to the next level, consider enrolling in our Ansible course at the link below!

    Course: Ansible for Complete Beginners

    What is Ansible? Ansible is an easy to learn automation tool that streamlines complex IT tasks with …

    57 Lessons
    6 Quizzes
    8 Labs
    18.5 Hr

    This post will dive into the Ansible copy module, covering everything from basic syntax to advanced usage options. By the end, you’ll have a solid understanding of how to use this module to streamline your automation tasks.

    Ansible Copy Module Syntax and Overview

    At its core, the Ansible copy module is designed to copy files from the local machine to a remote server. This function is crucial for managing configurations and ensuring that the necessary files are present on your servers for applications to run correctly. The module’s simplicity does not detract from its power; with just a few lines of code, you can automate what would otherwise be a tedious manual process.

    The basic syntax for the Ansible copy module looks something like this:

    - name: Copy file from local to remote
        src: /path/to/local/file
        dest: /path/to/remote/destination

    In this example, src specifies the path to the file on the local machine that you want to copy, while dest indicates the path on the remote server where the file should be placed. This simple yet effective syntax is the foundation upon which the copy module operates, offering both clarity and control in your automation tasks.

    The copy module also comes with a variety of options to customize its behavior. For instance, you can set permissions, change the owner and group of the copied file, and even decide whether to overwrite existing files. These options are what make the copy module not just a tool for copying files, but a powerful instrument for managing state across your environments.

    In the next sections, we’ll explore these options in more detail and provide practical examples of how to leverage the Ansible copy module in real-world scenarios. Whether you’re looking to copy a single file or synchronize entire directories, understanding these fundamentals is the first step towards mastering file management with Ansible.

    Copying Files from Local to Remote with Ansible

    Automating the transfer of files from your workstation to remote servers is a breeze with Ansible’s copy module. Here’s a straightforward example of how to execute this task. Let’s say you have a configuration file that needs to be updated across several servers. The following Ansible task does exactly that:

    - name: Copy a single file with Ansible
        src: /path/to/local/config.yml
        dest: /path/to/remote/config.yml

    This task picks up config.yml from your local directory and places it into the specified path on the remote machine. What stands out here is the simplicity and elegance of the operation. There’s no need for complex scripts or manual SSH file transfers. Just a few lines of YAML, and you’re set to replicate files across your infrastructure with pinpoint accuracy.

    This module isn’t just about pushing files around; it embodies the essence of automation by making repetitive tasks effortless and error-free. The ability to copy files from local to remote is foundational in many automation scenarios, whether it’s deploying application configurations, updating scripts, or provisioning new servers with the necessary files to get them up and running.

    Using the Ansible copy module, you ensure that your deployments are consistent, your configurations are correct, and your infrastructure management is as efficient as possible. This approach not only saves time but also significantly reduces the possibility of human error, leading to more reliable and predictable IT operations.

    Setting File Owners, Groups, and Permissions with Ansible

    When it comes to managing files on remote servers, it’s crucial not just to place them in the right location but also to ensure they have the appropriate permissions, ownership, and group settings. This is where Ansible’s copy module truly shines, offering granular control over these attributes. Let’s dive into how you can precisely dictate these settings for your files during the copy process.

    To set the owner, group, and permissions of a file you’re copying, you can use the owner, group, and mode options respectively. Here’s a practical example:

    - name: Copy file and set permissions with Ansible
        src: /path/to/local/
        dest: /path/to/remote/
        owner: webadmin
        group: webgroup
        mode: '0644'

    In this task, is transferred to the remote server. Upon arrival, the file’s ownership is set to the webadmin user, and it’s associated with the webgroup group. The mode option specifies the file’s permissions—in this case, 0644 means that the file is readable by anyone, but only writable by the owner.

    Understanding Permission Modes:

    The mode option uses UNIX-style file permissions, where the first digit represents special permissions, and the following three digits represent the owner’s, group’s, and others’ permissions, respectively. Each digit is a sum of:

    • 4 for read,
    • 2 for write,
    • 1 for execute.

    For directories or executable files, you might use 0755, which allows the owner full control, while the group and others can read and execute but not write.

    Copying Entire Directories

    You can copy an entire directory by setting the src and dest to something like that shown below:

    - name: Copy file and set permissions with Ansible
        src: /path/to/local/dir/
        dest: /path/to/remote/dir/

    Adding a trailing slash, like dir/ means that only the specific directory and it’s immediate children will be copied. If you remove the trailing slash (dir), then the directory will be copied recursively.

    If path is a directory, it is copied recursively. In this case, if path ends with “/”, only inside contents of that directory are copied to destination. Otherwise, if it does not end with “/”, the directory itself with all contents is copied. This behavior is similar to the rsync command line tool.

    Comparing Ansible Copy vs. Ansible Fetch Modules

    In the world of Ansible automation, both the copy and fetch modules serve crucial but distinct roles in managing files across your environments. Understanding the differences and appropriate use cases for each can significantly enhance your automation strategies. Here’s a quick comparison to help you decide when to use one over the other.

    Ansible Copy Module

    The copy module is designed to transfer files from the local machine (where Ansible is running) to remote machines. Its primary use case is deploying files, such as configuration files or scripts, that need to be present on one or more remote servers. The copy module offers a range of options for setting file permissions, ownership, and other attributes upon transfer, making it incredibly versatile for ensuring that files not only get where they need to go but also have the correct settings applied.

    Ansible Fetch Module

    Conversely, the fetch module does the opposite of the copy module. It is used to retrieve files from remote machines back to the local machine. This could be useful for gathering logs, collecting configuration files for backup, or any scenario where you need to consolidate information from multiple servers to a single location. The fetch module can also preserve the file permissions and ownership of the retrieved files, ensuring that vital metadata is not lost in the transfer.

    When to Use Each

    • Use the copy module when: You need to push files out to your remote servers. This is common for configuration management, deploying updated scripts, or ensuring specific files are present across your infrastructure.
    • Use the fetch module when: You need to gather files from your remote servers back to your local machine. This is ideal for backing up configurations, collecting logs, or aggregating data that needs to be processed or reviewed centrally.

    Practical Example: Combining Copy and Fetch

    Imagine a scenario where you need to update a configuration file across all servers and then collect logs from each server to verify the changes took effect. You could first use the copy module to distribute the updated configuration file and then use the fetch module to retrieve the latest logs from each server:

    - name: Update configuration and fetch logs
      hosts: all
        - name: Distribute updated configuration file
            src: /path/to/new/config.yml
            dest: /etc/app/config.yml
        - name: Fetch logs from servers
            src: /var/log/app.log
            dest: /local/path/logs/{{ inventory_hostname }}.log

    This approach not only ensures that your configurations are consistent across the board but also allows you to immediately verify the impact of those changes, illustrating the complementary nature of the copy and fetch modules in Ansible’s ecosystem.

    Understanding when and how to use the copy and fetch modules equips you with the flexibility to manage your infrastructure effectively, whether you’re deploying new changes or auditing existing configurations.


    To wrap up, mastering the Ansible copy module and understanding when to leverage it alongside other modules like fetch and template is a cornerstone of effective IT automation. Whether you’re distributing static files across your fleet, collecting critical data, or dynamically generating configurations tailored to each server, Ansible provides the tools you need to streamline these processes.

    Have you used the Ansible copy module or any of its counterparts in your projects? Do you have tips, tricks, or insights that could benefit others in the community? Join the conversation below and share your stories and questions.

    Dive Deeper into Ansible: If you’re looking to expand your Ansible knowledge and explore more advanced topics, consider enrolling in a course that delves deeper into automation best practices and complex workflows. Server Academy‘s comprehensive curriculum offers a range of courses designed to elevate your skills, from beginner to advanced levels.

    Coding and AutomationDevOpsLinux

    Want to improve your IT skillset? Start with a free account and get access to our IT labs!


    Sign up free and start learning today!

    Practice on REAL servers, learn from our video lessons, interact with the Server Academy community!

    0 0 votes
    Lesson Rating
    Notify of
    profile avatar
    Inline Feedbacks
    View all comments