AnsiblePilot — Master Ansible Automation

AnsiblePilot is the leading resource for learning Ansible automation, DevOps, and infrastructure as code. Browse over 1,400 tutorials covering Ansible modules, playbooks, roles, collections, and real-world examples. Whether you are a beginner or an experienced engineer, our step-by-step guides help you automate Linux, Windows, cloud, containers, and network infrastructure.

Popular Topics

About Luca Berton

Luca Berton is an Ansible automation expert, author of 8 Ansible books published by Apress and Leanpub including "Ansible for VMware by Examples" and "Ansible for Kubernetes by Example", and creator of the Ansible Pilot YouTube channel. He shares practical automation knowledge through tutorials, books, and video courses to help IT professionals and DevOps engineers master infrastructure automation.

Ansible Tags: Run Specific Tasks Selectively (Complete Guide)

By Luca Berton · Published 2024-01-01 · Category: installation

Complete guide to Ansible tags. Run specific tasks with --tags, skip tasks, tag roles and includes, and organize playbooks with tagging strategies.

Ansible tags are a feature that allows users to selectively control which tasks in a playbook are executed. They are an essential tool for optimizing automation workflows, especially in complex playbooks. This article explains what Ansible tags are, their usage, and best practices for implementing them.

What Are Ansible Tags?

Tags in Ansible are labels assigned to tasks or plays within a playbook. They enable users to execute specific parts of a playbook, skipping others based on the tags provided during execution.

Key Features:

  • Selective Execution: Run only tasks with specified tags.
  • Improved Efficiency: Save time by skipping unnecessary tasks.
  • Flexibility: Apply multiple tags to a single task or play.

How Do Ansible Tags Work?

Tags are added to tasks, roles, or entire plays using the tags keyword. During playbook execution, you can specify which tags to include or skip using command-line options.

Example: Using Tags in a Playbook

- name: Configure web servers
  hosts: webservers
  tasks:
    - name: Install Nginx
      apt:
        name: nginx
        state: present
      tags:
        - install
        - web

    - name: Start Nginx service
      service:
        name: nginx
        state: started
      tags:
        - start
        - web

In this example:

  • The install tag applies to the Nginx installation task.
  • The start tag applies to the task starting the Nginx service.
  • Both tasks share the web tag.

Running Tagged Tasks

To execute only tasks with a specific tag, use the --tags option: 

ansible-playbook playbook.yml --tags install

Skipping Tags

To skip tasks with specific tags, use the --skip-tags option: 

ansible-playbook playbook.yml --skip-tags start

See also: Can Ansible Be Used to Manage Windows Systems?

Tagging Roles and Plays

Tags can also be applied to roles and entire plays for broader control.

Example: Tagging Roles

- hosts: all
  roles:
    - role: webserver
      tags:
        - setup

Example: Tagging Plays

- name: Database setup
  hosts: dbservers
  tags:
    - database

Use Cases for Ansible Tags

  1. Selective Testing:
Run specific tasks during testing without executing the entire playbook.
  1. Environment-Specific Tasks:
Use tags to differentiate tasks for production, staging, or development environments.
  1. Debugging:
Isolate tasks with issues for quicker debugging.
  1. Partial Updates:
Apply updates to only certain parts of your infrastructure.

See also: Can Ansible Manage Windows? Complete Windows Automation Guide

Best Practices for Using Tags

  1. Use Descriptive Tags:
Name tags based on their purpose (e.g., install, deploy, restart).
  1. Organize Tags:
Group related tasks under shared tags for better management.
  1. Avoid Overuse:
Limit the number of tags to maintain clarity and simplicity.
  1. Document Tags:
Include a list of available tags in your playbook’s documentation or comments.
  1. Test Tagged Tasks:
Regularly test tasks under each tag to ensure reliability.

Limitations of Tags

  • Dependency Issues: Tasks that depend on others may fail if skipped.
  • Complexity: Overusing tags can complicate playbooks and execution workflows.

Conclusion

Ansible tags provide a powerful way to control playbook execution, enabling selective task runs and improving efficiency. By implementing tags strategically and following best practices, you can streamline your automation workflows and save valuable time.

Learn More About Ansible Tags

See also: Ansible on Windows: Complete Guide to Windows Automation (2026)

Basic Tags

tasks:
  - name: Install packages
    ansible.builtin.package:
      name: nginx
    tags: install

  - name: Configure nginx
    ansible.builtin.template:
      src: nginx.conf.j2
      dest: /etc/nginx/nginx.conf
    tags: configure

  - name: Start service
    ansible.builtin.service:
      name: nginx
      state: started
    tags: service

Run or Skip Tags

# Run only tagged tasks
ansible-playbook site.yml --tags "install"
ansible-playbook site.yml --tags "install,configure"

# Skip specific tags
ansible-playbook site.yml --skip-tags "configure"

# List all tags in playbook
ansible-playbook site.yml --list-tags

Multiple Tags Per Task

- name: Deploy app config
  ansible.builtin.template:
    src: config.j2
    dest: /etc/myapp/config.yml
  tags:
    - configure
    - deploy
    - myapp

Tag Roles

- hosts: webservers
  roles:
    - { role: common, tags: common }
    - { role: webserver, tags: [web, nginx] }
    - { role: monitoring, tags: monitoring }

Tag Entire Plays

- hosts: webservers
  tags: webservers
  tasks:
    - name: All tasks inherit the play tag
      package:
        name: nginx

Special Tags

TagDescription
alwaysAlways runs (unless --skip-tags always)
neverNever runs (unless --tags never or explicit)
taggedAll tagged tasks
untaggedAll untagged tasks
allEverything (default)
- name: Debug info (only when asked)
  debug:
    msg: "Debug mode active"
  tags: never  # Must explicitly --tags debug,never

- name: Gather facts (always)
  setup:
  tags: always

Tag Inheritance

Tags on blocks, roles, and plays are inherited by child tasks:

- block:
    - name: Install packages
      package: name=nginx
    - name: Start service
      service: name=nginx state=started
  tags: webserver
  # Both tasks get the 'webserver' tag

Common Tag Patterns

# Environment tags
tags: [production, deploy]

# Phase tags
tags: [phase1, install]

# Component tags
tags: [database, postgresql]
# Deploy only database in production
ansible-playbook site.yml --tags "database"

# Run everything except monitoring
ansible-playbook site.yml --skip-tags "monitoring"

FAQ

Do handlers respect tags?

Handlers run when notified, regardless of tags. A tagged task that changes will trigger its handler even if the handler isn't tagged.

Can I use tags in roles?

Yes — tag the role in the playbook, or tag individual tasks within the role. Role-level tags apply to all tasks in that role.

Should I tag every task?

No — tag logical groups. Over-tagging makes playbooks harder to maintain. Use tags for phases (install, configure, deploy) or components (web, db, monitoring).

Basic Tags

- hosts: all
  tasks:
    - name: Install packages
      apt: { name: nginx, state: present }
      tags: [packages]
      become: true

    - name: Deploy config
      template: { src: nginx.conf.j2, dest: /etc/nginx/nginx.conf }
      tags: [config]
      become: true

    - name: Start service
      service: { name: nginx, state: started }
      tags: [service]
      become: true

Run Specific Tags

# Only run "config" tasks
ansible-playbook site.yml --tags config

# Run multiple tags
ansible-playbook site.yml --tags "packages,config"

# Skip specific tags
ansible-playbook site.yml --skip-tags packages

# List all available tags
ansible-playbook site.yml --list-tags

Tag Roles

- hosts: webservers
  roles:
    - role: webserver
      tags: [web]
    - role: monitoring
      tags: [monitoring]
# Only run webserver role
ansible-playbook site.yml --tags web

Tag Includes

- import_tasks: install.yml
  tags: [install]

- include_tasks: configure.yml
  tags: [configure]

Multiple Tags Per Task

- name: Deploy SSL certificate
  copy:
    src: cert.pem
    dest: /etc/ssl/cert.pem
  tags:
    - ssl
    - security
    - deploy

Special Tags

# 'always' — runs even when filtering by tags
- name: Gather facts
  setup:
  tags: always

# 'never' — only runs when explicitly called
- name: Dangerous cleanup
  shell: rm -rf /tmp/*
  tags: never
# Run 'never' tagged tasks explicitly
ansible-playbook site.yml --tags cleanup,never

Tag Inheritance

# Tags on blocks apply to all tasks inside
- block:
    - apt: { name: nginx }
    - apt: { name: certbot }
    - template: { src: nginx.conf.j2, dest: /etc/nginx/nginx.conf }
  tags: [web]
  become: true

Tagging Strategy

# Recommended: use consistent tag categories
tasks:
  # Component tags
  - apt: { name: nginx }
    tags: [nginx, packages]

  # Phase tags
  - template: { src: config.j2, dest: /etc/app.conf }
    tags: [nginx, config]

  # Action tags
  - service: { name: nginx, state: restarted }
    tags: [nginx, service, restart]
# All nginx tasks
ansible-playbook site.yml --tags nginx

# Only package installation
ansible-playbook site.yml --tags packages

# Everything except restart
ansible-playbook site.yml --skip-tags restart

Play-Level Tags

- hosts: webservers
  tags: [web]
  tasks:
    - apt: { name: nginx }  # Inherits 'web' tag

- hosts: dbservers
  tags: [database]
  tasks:
    - apt: { name: postgresql }  # Inherits 'database' tag

FAQ

Do tags affect handlers?

Handlers run if notified, regardless of tags. However, if the task that notifies is skipped by tags, the handler won't be triggered.

import_tasks vs include_tasks with tags?

import_tasks: tags apply to individual tasks inside. include_tasks: tags apply to the include statement itself, but you can also pass tags to included tasks.

Can I combine --tags and --skip-tags?

Yes: --tags deploy --skip-tags dangerous runs all 'deploy' tasks except those also tagged 'dangerous'.

Should I tag every task?

No — tag strategically. Common patterns: tag by component (nginx, postgres), by phase (install, configure, deploy), or by action (restart, backup).

See also

Category: installation

Browse all Ansible tutorials · AnsiblePilot Home