Instalación de CLI de Azure en macOS: versión preliminar

CLI de Azure es una herramienta de línea de comandos multiplataforma para administrar Azure recursos de forma interactiva o a través de scripts.

En macOS, CLI de Azure está pasando de la fórmula Homebrew Core hacia un modelo de instalación más fácil de mantener y flexible. El nuevo modelo incluye:

  • Homebrew Cask (recomendado para la mayoría de los usuarios)
  • Tarball (recomendado para entornos sin conexión o aislados)

Esta experiencia se encuentra actualmente en versión preliminar y se convertirá en el enfoque de instalación estándar en una versión futura.

¿Por qué usar Homebrew Cask?

  • Experiencia de instalación y actualización más sencilla
  • Administra automáticamente las dependencias
  • Se alinea con el modelo de instalación compatible futuro.

¿Qué está cambiando?

CLI de Azure está evolucionando para admitir la autenticación más segura, incluida la autenticación basada en agente. Estas capacidades requieren un modelo de instalación basado en contenedores. Como resultado, estamos realizando la transición de Homebrew Core a Homebrew Cask. Este cambio no quita ni limita ninguna funcionalidad de CLI de Azure existente. Homebrew Cask es totalmente compatible con todas las características y versiones actuales de CLI de Azure.

Este cambio mejora la coherencia entre entornos y proporciona una mejor compatibilidad con escenarios como la instalación sin conexión y los entornos de implementación controlados.

Importante

CLI de Azure está actualmente en una fase de versión preliminar para el modelo de instalación de Homebrew Cask. Durante esta fase, la instalación solo está disponible a través de una pulsación personalizada de Homebrew.

  • Método actual: brew install azure-cli
  • Nuevos métodos (fase de versión preliminar):
    • Homebrew Cask mediante pulsación personalizada
      1. brew tap azure/azure-cli
      2. brew install --cask azure-cli-preview
    • Instalación basada en Tarball

Elección de un método de instalación

Use las instrucciones siguientes para seleccionar el método de instalación que mejor se adapte a su escenario:

Escenario Método recomendado
Mayoría de los usuarios Homebrew Cask
Sistemas sin conexión o aislados físicamente Tarball
Ubicación de instalación personalizada necesaria Tarball

Instalación de CLI de Azure mediante Homebrew Cask

Homebrew proporciona la experiencia de instalación más sencilla y fácil de mantener para CLI de Azure en macOS. Controla la instalación, las actualizaciones y la eliminación mediante flujos de trabajo de administración de paquetes estándar.

Prerequisites

  • macOS (Apple Silicon o Intel)
  • Homebrew instalado

Si CLI de Azure ya está instalado con la fórmula Homebrew, desinstálela antes de continuar para evitar conflictos:

brew uninstall azure-cli

Instalación de la CLI de Azure

Esto instala CLI de Azure mediante el Homebrew Cask desde el agregador personalizado de CLI de Azure. Este es el único método de instalación de Homebrew admitido durante la fase de versión preliminar.

brew tap azure/azure-cli
brew install --cask azure-cli-preview

Comprobación de la instalación

Después de la instalación, confirme que CLI de Azure está disponible:

az --version

Actualizar CLI de Azure

Para actualizar a la versión más reciente:

brew update && brew upgrade --cask azure-cli-preview

Desinstalación de la CLI de Azure

Para quitar CLI de Azure:

brew uninstall --cask azure-cli-preview
brew untap azure/azure-cli

Después de la fase de vista previa

Cuando la instalación de Homebrew Cask esté disponible con carácter general:

  • El método de instalación de la versión preliminar (azure-cli-preview a través de un tap personalizado) se interrumpirá.
  • CLI de Azure estarán disponibles en el repositorio oficial de Homebrew Cask.

Instale CLI de Azure mediante:

brew install --cask azure-cli
# Or
brew install azure-cli

Las instalaciones existentes que usan la fórmula Homebrew Core deben migrar a la instalación basada en Cask. La fórmula Homebrew Core ya no se admitirá después de esta transición.

Instalar CLI de Azure mediante un Tarball

Use este método si:

  • Homebrew no está disponible
  • El acceso a Internet está restringido
  • Necesita control total sobre la ubicación de instalación.

Este método se usa comúnmente en entornos empresariales, regulados o aislados de redes externas.

Prerequisites

  • macOS (Apple Silicon o Intel)
  • Python 3.13 instalado a través de cualquier método (python.org, pyenv, etc.)

Descargar el archivo tarball

En una máquina con acceso a Internet, puede descargar automáticamente la última CLI de Azure tarball para su arquitectura:

ARCH=$(uname -m)
VER=$(curl -s https://api.github.com/repos/Azure/azure-cli/releases/latest | grep tag_name | cut -d '"' -f4 | sed 's/azure-cli-//')
curl -L -o az.tar.gz "https://github.com/Azure/azure-cli/releases/download/azure-cli-$VER/azure-cli-$VER-macos-$ARCH.tar.gz"

Este script detecta tu arquitectura y descarga la última versión del archivo tar de CLI de Azure desde la página de lanzamientos de CLI de Azure.

  • arm64 indica Apple Silicon
  • x86_64 indica Intel

La selección de la arquitectura correcta garantiza la compatibilidad y el rendimiento óptimo.

Sugerencia

Para entornos sin conexión, ejecute este comando en una máquina con acceso a Internet y, a continuación, transfiera el tarball descargado al sistema de destino.

Extraer en el directorio de instalación

Elija un directorio en el que se debe instalar CLI de Azure:

mkdir -p $HOME/lib/azure-cli
tar -xzf az.tar.gz -C $HOME/lib/azure-cli

Configuración de las variables de entorno

CLI de Azure requiere acceso a un entorno de ejecución de Python. Configure su entorno para que apunte a Python y los binarios de CLI de Azure.

Agregue lo siguiente al perfil de shell (~/.zshrc o ~/.bashrc):

export AZ_PYTHON="/path_to_python"
export PATH="/target_directory_path/bin:$PATH"

Vuelva a cargar la configuración del shell:

source ~/.zshrc

Comprobación de la instalación

az --version

Actualizar CLI de Azure

Para actualizar CLI de Azure en un entorno sin conexión, descargue una tarball más reciente y extráigala a través de la instalación existente:

sudo tar -xzf az.tar.gz -C /target_directory_path

Desinstalación de la CLI de Azure

Quite el directorio de instalación:

sudo rm -rf /target_directory_path

A continuación, quite las entradas AZ_PYTHON y PATH del perfil de shell.

Troubleshooting

Si se produce un problema al instalar o usar el CLI de Azure con Homebrew Cask o el método Tarball, estos son algunos errores comunes (muchos de los cuales son específicos de Homebrew). Si experimenta un problema que no se trata aquí, presente un problema en GitHub.

no se encontró CLI de Azure

Asegúrese de que path incluye el directorio de instalación:

echo $PATH

La finalización no funciona

La instalación de CLI de Azure Homebrew (ya sea mediante fórmula o cask) proporciona un archivo de finalización denominado az en el directorio de finalizaciones administradas de Homebrew. Para habilitar la finalización, siga las instrucciones de Homebrew.

Para Zsh, agregue las dos líneas siguientes a la parte inferior de su archivo .zshrc, luego guarde y vuelva a cargar su perfil de Zsh.

autoload bashcompinit && bashcompinit
source $(brew --prefix)/etc/bash_completion.d/az

No se puede encontrar Python ni los paquetes instalados

Puede haber una incompatibilidad de la versión secundaria u otro problema durante la instalación de Homebrew. CLI de Azure no usa un entorno virtual de Python, por lo que se basa en buscar la versión de Python instalada. Una posible solución consiste en instalar y volver a vincular la dependencia de python@3.13 desde Homebrew.

brew update && brew install python@3.13 && brew upgrade python@3.13
brew link --overwrite python@3.13

El servidor proxy bloquea la conexión

Es posible que no pueda obtener recursos de Homebrew a menos que lo configure para usar el proxy. Siga las instrucciones de configuración del proxy de Homebrew.

Importante

Si está detrás de un proxy, HTTP_PROXY y HTTPS_PROXY deben configurarse para conectarse a los servicios de Azure con la CLI de Azure. Si no usa la autenticación básica, debe exportar estas variables en el .bashrc archivo. Siga siempre las directivas de seguridad de su empresa y los requisitos del administrador del sistema.

Para obtener los recursos de botella de Homebrew, el proxy debe permitir conexiones HTTPS a las siguientes direcciones:

  • https://formulae.brew.sh
  • https://homebrew.bintray.com

Pasos siguientes

Ahora que ha instalado la CLI de Azure en macOS, realice un breve recorrido por sus características y comandos comunes.

Comienza con la CLI de Azure

  • Last updated on