Como instalar um módulo Magento 2 manualmente (sem composer)

Composer é o gerenciador de dependências oficial do PHP e também do Magento. É com ele que instalamos o Magento, e também módulos e temas para nossas lojas. No entanto existem casos onde instalar um módulo Magento 2 via composer não é mais rápido, prático e nem mesmo a melhor forma. Nestes casos, fazer a instalação de um módulo ou tema manualmente pode ser mais interessante.

Quando estamos desenvolvendo, ou queremos modificar um módulo ou tema não devemos usar o composer. Como sabemos, nunca devemos modificar arquivos na pasta /vendor, afinal é ele – o composer– quem gerencia o que tem ali.

Porque faríamos isso então?

Se o composer pode gerenciar módulos e dependências pra gente, porque eu iria instalar um módulo manualmente? Bom, eu particularmente posso pensar em alguns pontos positivos e negativos para isso.

Vantagens

• É mais rápido que instalar via composer
• É mais fácil e rápido de versionar e atualizar
• Permite dar manutenção e modificar, especialmente se for um módulo próprio
• Ideal para instalações de módulos temporários ou pontuais (ex: quando precisamos de um módulo específico para depurar algum ponto durante o desenvolvimento)
• Maior controle sob o que estamos alterando e atualizando

Desvantagens

• Difícil de garantir/verificar compatibilidade com outros módulos e bibliotecas já instaladas
• Difícil garantir compatibilidade com a versão do PHP e dependências de extensões
• Mais complicado para manter o módulo e suas dependências atualizadas
• É mais fácil cometer erros na instalação afetando o funcionamento do componente

Como podemos perceber, há alguns cenários onde instalar um módulo ou tema manualmente pode ser mais interessante.

Como instalar um módulo manualmente – Passo a passo

Após baixar o arquivo do módulo/tema que queremos instalar, devemos:

1. Localizar a pasta raiz do componente – geralmente é a pasta principal, mas em alguns casos o dono do projeto pode ter colocado estes arquivos em uma subpasta. Entender a estrutura de um módulo/tema nos ajudará a saber o que estamos buscando.
2. Criar a pasta onde copiaremos estes arquivos
3. Executar operações de atualização de rotina para “instalar” o componente

Estrutura de um módulo/tema Magento

Todo componente Magento possui um arquivo registration.php localizado na sua pasta principal. Ao encontrar este arquivo, você provavelmente estará na pasta raiz do componente que deseja instalar. E é essa pasta e suas subpastas que vamos copiar.

Este arquivo é responsável por registrar o componente dentro do Magento. No nosso caso, será importante olharmos este arquivo para identificar o nome do componente. Por exemplo:

<?php
\Magento\Framework\Component\ComponentRegistrar::register(
    \Magento\Framework\Component\ComponentRegistrar::MODULE,
    'RicardoMartins_PagSeguro',
    __DIR__
);

Como podemos ver, o nome do componente é informado no segundo parâmetro da chamada ao método register, e geralmente segue o padrão Fornecedor_NomeDoModulo.

Instalando um módulo ou tema manualmente (sem composer)

No exemplo acima, o nome do fornecedor (vendor) do módulo é RicardoMartins e o nome do módulo é PagSeguro. Também sabemos que trata-se de um módulo, pois no parâmetro anterior temos ::MODULE, indicando se tratar de um módulo e não de um ::THEME (Tema).

Criando a pasta de um módulo

Módulos instalados manualmente ou que estamos desenvolvendo devem ser colocados na pasta app/code/<Fornecedor>/<NomeDoModulo>.

Sendo assim, devemos criar a(s) pasta(s) app/code/RicardoMartins/PagSeguro na raiz do nosso Magento. Note que a pasta raiz do Magento neste caso não será a pasta /pub, mas sim uma pasta acima.

Criando a pasta de um tema

Caso seu componente seja um tema, o procedimento é igual, porém criaremos o tema na pasta app/design/frontend/<fornecedor>/<tema>.

A != a

O Magento é “chato” nesse assunto. Portanto, fique atento à caixa alta e baixa. Se no registration.php seu módulo se chama ModuloTeste, seu módulo terá problemas se criar uma pasta chamada Moduloteste.

Executando operações de rotina

Após copiar a pasta de seu componente no lugar certo, é preciso informar ao Magento que o componente existe.

No caso de temas, a limpeza de cache e geração de arquivos estáticos costumam ser suficientes para ter o tema disponível para configuração na área administrativa. Ou seja, bastará executar bin/magento cache:clean e bin/magento setup:static-content:deploy (se estiver em modo production).

Já no caso de módulos, eles precisam ser ativados, compilados e ter seus scripts de setup executados. Se este é um novo módulo em sua loja, basta digitar bin/magento setup:upgrade e bin/magento setup:di:compile.

⚠️ Atenção às dependências

Nem todos os módulos suportam instalações manuais.

Ao encontrar um arquivo composer.json na raiz de um módulo, verifique se existem dependências a serem adicionadas. Veja o exemplo:

{
    "name": "magenteiro/module-mautic",
    "description": "Mautic Integration",
    "type": "magento2-module",
    "license": "proprietary",
    "authors": [
        {
            "name": "Ricardo Martins",
            "email": "[email protected]"
        }
    ],
    "minimum-stability": "dev",
    "require": {
        "mautic/api-library": "^2.6"
    },
    "autoload": {
        "psr-4": {
            "Magenteiro\\Mautic\\": ""
        },
        "files": [
            "registration.php"
        ]
    }
}

Módulos podem precisar de outros módulos e/ou bibliotecas para funcionarem corretamente. Estas bibliotecas por sua vez podem não ter sido desenvolvidas nos padrões do Magento e possuirem formas diferentes de serem carregadas (autoload). Elas podem ainda depender de outros componentes, que dependem de outros, e assim sucessivamente.

Lidar com esses cenários manualmente é na maioria das vezes bem difícil e faz com que o processo de instalação manual seja inviável e impossível de manter no curto e longo prazo.

Para esses casos, use o composer.

E claro, se quiser aprender a criar módulos e componentes para Magento 2, junte-se à nossa comunidade no Magento 2: O Curso.

Este artigo foi recomendado por César Galvani, da MageUni. Quer recomendar ou escrever o próximo? Entre em contato.

• Sobre
• Últimos Posts

Ricardo Martins

É desenvolvedor web há 16 anos e um dos primeiros certificados pela Magento no Brasil. Instrutor de mais de 11 cursos Magento (os principais no magenteiro.com/cursos) com mais de 14 mil alunos de 105 países, é também criador do módulo PagSeguro Transparente, usado em mais de 12 mil lojas.

Últimos posts por Ricardo Martins (exibir todos)

• Guest checkout bloqueado na API REST do Magento 2? Confira isso. - 7 de julho de 2026
• Você precisa testar esta plataforma de e-commerce - 9 de fevereiro de 2026
• A hora de montar o seu OnlyFans chegou! Veja 8 ideias pra começar o seu. - 4 de dezembro de 2024