{"id":9127,"library":"model-archiver","title":"Model Archiver","description":"Model Archiver is a Python library and command-line tool used for creating archives of trained neural network models. These archives, typically with a .mar extension, are specifically structured to be consumed by the MXNet-Model-Server for efficient inference. The PyPI package (version 1.0.3) serves as a standalone tool, although its core functionality has largely evolved into 'torch-model-archiver' for the 'TorchServe' (formerly 'Multi-Model-Server') ecosystem.","status":"maintenance","version":"1.0.3","language":"en","source_language":"en","source_url":"https://github.com/awslabs/mxnet-model-server/tree/master/model-archiver","tags":["machine learning","model deployment","MXNet","AWS","archive","model serving"],"install":[{"cmd":"pip install model-archiver","lang":"bash","label":"Install stable release"}],"dependencies":[{"reason":"Fundamental package for scientific computing.","package":"numpy"},{"reason":"Image processing capabilities, common in vision models.","package":"Pillow"},{"reason":"Used for configuration file parsing.","package":"pyyaml"},{"reason":"AWS SDK for Python, often used for S3 integration (optional).","package":"boto3","optional":true},{"reason":"Used for data serialization, especially with ONNX models.","package":"protobuf"},{"reason":"HTTP client for various internal communications.","package":"requests"},{"reason":"gRPC Python utilities for communication with model servers.","package":"grpcio"},{"reason":"Tools for gRPC, often used in conjunction with grpcio.","package":"grpcio-tools"}],"imports":[{"note":"While a programmatic interface exists, `model-archiver` is primarily designed for command-line use. Direct import of internal classes is less common for end-user model archiving.","symbol":"ModelArchiver","correct":"from model_archiver.mar import ModelArchiver"}],"quickstart":{"code":"model-archiver --model-name my_mxnet_model \\\n               --version 1.0 \\\n               --model-path ./path_to_model_artifacts/ \\\n               --handler my_handler.py \\\n               --extra-files requirements.txt,config.json \\\n               --export-path ./model_store/\n\n# Example `my_handler.py` (simplified structure):\n# class MXNetHandler:\n#     def __init__(self):\n#         self.model = None\n#     def initialize(self, context):\n#         properties = context.system_properties\n#         model_dir = properties.get(\"model_dir\")\n#         # Load model, e.g., using MXNet's gluon.nn\n#         # self.model = gluon.nn.load_param(os.path.join(model_dir, 'model_params.params'))\n#     def preprocess(self, data):\n#         # Preprocess input data\n#         return data\n#     def inference(self, data):\n#         # Perform inference using self.model\n#         return self.model(data)\n#     def postprocess(self, data):\n#         # Postprocess inference results\n#         return data","lang":"bash","description":"Create a model archive (.mar file) for an MXNet model. This command packages your model artifacts, a custom handler script (`my_handler.py`), and any extra files (like `requirements.txt` or configuration files) into a single archive. The generated .mar file is then placed in the specified `export-path`. Ensure your handler script correctly implements the `initialize`, `preprocess`, `inference`, and `postprocess` methods for your specific model."},"warnings":[{"fix":"For new projects or PyTorch models, consider using `pip install torch-model-archiver` and the associated `torch-model-archiver` CLI. This provides access to the latest features, bug fixes, and active community support.","message":"The `model-archiver` PyPI package (version 1.0.3) is primarily designed for the legacy MXNet-Model-Server. For modern deep learning model serving, particularly with PyTorch, the actively maintained and recommended tool is `torch-model-archiver`, which is part of the `TorchServe` ecosystem (evolved from Multi-Model-Server).","severity":"breaking","affected_versions":"<=1.0.3"},{"fix":"For packaging models, rely on the `model-archiver` command-line tool. If programmatic integration is essential, consult the source code on GitHub for direct API usage patterns, focusing on the `model_archiver.mar` module.","message":"The `model-archiver` is predominantly a command-line interface tool. While it exposes Python modules, its intended usage for creating model archives is through its CLI. Programmatic invocation of its internal functions is less common and may have limited dedicated documentation.","severity":"gotcha","affected_versions":"<=1.0.3"},{"fix":"Before archiving ONNX models, manually install the required libraries: `pip install protobuf onnx mxnet` (or the specific MXNet variant like `mxnet-cu101`). Ensure a protobuf compiler is also available in your environment.","message":"When packaging ONNX models, additional dependencies (`protobuf` compiler, `onnx`, `mxnet`) are not installed by default with `model-archiver`. Without these, ONNX model packaging will fail.","severity":"gotcha","affected_versions":"<=1.0.3"},{"fix":"For complex dependencies, either package them as a Python egg/wheel and include it via `--extra-files`, or adjust your handler to manually manage the Python path or use relative imports carefully. Alternatively, provide a `requirements.txt` with your `model-archiver` command for dependencies available on PyPI.","message":"Handling complex model project structures (e.g., multiple interdependent Python files in subdirectories) within the handler can lead to import errors. The archiving process might flatten directory structures, causing Python's import mechanism to fail.","severity":"gotcha","affected_versions":"<=1.0.3"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure `model-archiver` is installed via `pip install model-archiver`. If it is, locate your Python's script directory (e.g., `~/.local/bin` on Linux or `Scripts` in your virtual environment on Windows) and add it to your system's PATH, or explicitly call it using `python -m model_archiver.model_packaging`.","cause":"The `model-archiver` executable is not in your system's PATH, or the package was not installed correctly.","error":"model-archiver: command not found"},{"fix":"Provide a `requirements.txt` file listing all custom Python dependencies and pass it to `model-archiver` using the `--extra-files` argument (e.g., `--extra-files requirements.txt`). For packages not on PyPI, include their source or wheel files directly via `--extra-files` and handle installation within your custom handler's `initialize` method if necessary.","cause":"Your model's handler or auxiliary scripts require Python packages that are not part of the standard Python library or already installed in the serving environment, and these were not included in the archive.","error":"Model archive fails with missing dependencies: No module named 'your_dependency'"},{"fix":"Ensure a valid `signature.json` file is present in your `--model-path` directory. Refer to the MXNet-Model-Server documentation for the correct `signature.json` format. It defines the expected inputs and outputs for your model.","cause":"The `signature.json` file, which describes model inputs and outputs for MXNet-Model-Server, is either missing from your model artifacts or is malformed.","error":"Error: Signature file not found or invalid format."},{"fix":"When creating the archive for SageMaker multi-model endpoints, use `model-archiver` with `--archive-format no-archive`. Then, manually compress the resulting directory into a `.tar.gz` ensuring that the `MAR-INF` (manifest) directory is at the root level of the tarball. SageMaker needs to decompress directly to your model files and handler, not an extra parent directory.","cause":"SageMaker multi-model endpoints might treat a `.tar.gz` file as raw model artifacts rather than a model archive, failing to correctly extract and register the handler specified within.","error":"Error: \"No handler defined for model\" when deploying .tar.gz to SageMaker multi-model endpoint, even with handler in archive."}]}