Ansible Pilot

Creating a New Ansible Collection: A Step-by-Step Guide

How to use the ansible-galaxy command to create a new test.test Ansible collection.

August 9, 2023
Access the Complete Video Course and Learn Quick Ansible by 200+ Practical Lessons


Ansible Collections are a powerful way to organize and distribute your Ansible content, including modules, plugins, roles, and more. They allow you to package and share your automation resources in a structured and reusable manner. In this tutorial, we’ll walk you through the process of creating a new Ansible Collection using the ansible-galaxy command-line tool.

The Best Resources For Ansible


Video Course

Printed Book


Step by step

Step 1: Installation and Prerequisites Before you start, ensure that you have Ansible and the ansible-galaxy command-line tool installed on your system. If not, you can install Ansible by following the official documentation. Once installed, you’ll be ready to create your new Ansible Collection.

Step 2: Initialize a New Collection To create a new collection, open your terminal and run the following command:

ansible-galaxy collection init test.test

This command initializes a new collection named test.test. You should see an output confirming that the collection was created successfully.

ansible-galaxy collection init test.test
- Collection test.test was created successfully

Step 3: Explore the Collection Structure

After creating the collection, navigate to the collection’s directory. You can use the following command:

cd test/test

Inside this directory, you’ll find several subdirectories and files that make up your Ansible Collection’s structure:

Content of the “test/test” directory:

└── test
    └── test
        ├── docs
        ├── galaxy.yml
        ├── meta
        │   └── runtime.yml
        ├── plugins
        │   └──
        └── roles

6 directories, 4 files

Step 4: Making Necessary Changes At this point, you can start making the necessary changes to your collection. You can add new modules, plugins, roles, or any other content your automation requires. Modify the galaxy.yml file to reflect your collection’s information accurately.

Step 5: Building the Collection It’s time to build the collection once you’ve made the required changes and added your content. Building the collection packages all your content into a distributable archive. In your collection’s directory, run the following command:

ansible-galaxy collection build

This command will create a compressed archive file named after your collection and version, such as test-test-1.0.0.tar.gz. Created collection for test.test at /home/luca/collection/test/test/test-test-1.0.0.tar.gz

Step 6: Verifying the Build After running the build command, you’ll find the archive file in your current directory. You can verify its contents using the following commands:

file test-test-1.0.0.tar.gz
du -hs test-test-1.0.0.tar.gz
tar -tvf test-test-1.0.0.tar.gz

These commands will display information about the archive file, including its size, compression type, and the contents it contains.

$ file test-test-1.0.0.tar.gz 
test-test-1.0.0.tar.gz: gzip compressed data, was "test-test-1.0.0.tar", last modified: Wed Aug  9 14:56:25 2023, max compression, original size modulo 2^32 20480
$ du -hs test-test-1.0.0.tar.gz 
4.0K test-test-1.0.0.tar.gz

Content of the “test-test-1.0.0.tar.gz” archive:

-rw-r--r-- 0/0             714 2023-08-09 15:56 MANIFEST.json
-rw-r--r-- 0/0            1159 2023-08-09 15:56 FILES.json
-rw-r--r-- 0/0              68 2023-08-09 15:55
drwxr-xr-x 0/0               0 2023-08-09 15:55 docs/
drwxr-xr-x 0/0               0 2023-08-09 15:55 meta/
-rw-r--r-- 0/0            1374 2023-08-09 15:55 meta/runtime.yml
drwxr-xr-x 0/0               0 2023-08-09 15:55 plugins/
-rw-r--r-- 0/0             963 2023-08-09 15:55 plugins/


Congratulations! You’ve successfully created a new Ansible Collection named test.test and built an archive ready for distribution. You can now share or use your collection on Ansible Galaxy and Automation Hub in your automation projects. Creating and managing Ansible Collections empowers you to efficiently organize and distribute your automation resources, making it easier for you and others to leverage your automation efforts. Subscribe to the YouTube channel, Medium, and Website, X (formerly Twitter) to not miss the next episode of the Ansible Pilot.


Learn the Ansible automation technology with some real-life examples in my

My book Ansible By Examples: 200+ Automation Examples For Linux and Windows System Administrator and DevOps

BUY the Complete PDF BOOK to easily Copy and Paste the 250+ Ansible code

Want to keep this project going? Please donate

Access the Complete Video Course and Learn Quick Ansible by 200+ Practical Lessons
Follow me

Subscribe not to miss any new releases