AI Project Structure: Where to Keep Model Files

Updated 5 November 2026 · Standard formula, shown below

In an AI project, keep model files in a dedicated top-level directory such as models/ or artifacts/models/, separate from source code, data, and configuration. The exact layout depends on whether the files are trained checkpoints, downloaded pretrained weights, or small model definitions written as code; document the distinction so teammates and scripts can find the right files.

A practical project layout

A clear repository might look like this:

my-ai-project/
├── configs/
├── data/
│   ├── raw/
│   └── processed/
├── models/
│   ├── README.md
│   └── .gitkeep
├── notebooks/
├── scripts/
├── src/
│   └── project_name/
├── tests/
├── .gitignore
├── pyproject.toml
└── README.md

Here, models/ is the obvious place for model artifacts, while src/ contains the code that defines, loads, trains, or evaluates models. The sample directory is intentionally empty: large weights often should not be committed to ordinary source control. If a project tracks small fixtures or example weights, give them a clearly named subdirectory rather than mixing them with production checkpoints.

There is no universal AI-project standard that requires a folder named models. Some teams use checkpoints/, weights/, or artifacts/. Consistency and clear documentation matter more than the particular name.

What “model” can mean

The question “where do models go?” has two common answers because “model” can refer to different things:

Model implementation: Python or other source code describing a network, estimator, or inference wrapper. Put it in the application package, for example src/project_name/models/.
Model artifact: Saved weights, a checkpoint, or a serialized estimator produced by training or obtained from a model provider. Store it outside the source package, commonly under a local models/ directory or in managed artifact storage.
Model configuration: Parameters such as architecture settings, preprocessing choices, and training options. Keep these in configs/ or alongside a named experiment, rather than embedding every setting in a binary checkpoint.

For example, src/project_name/models/classifier.py can define a classifier class, while models/classifier-v3/ holds its trained weights and a short README identifying the matching code and configuration. Separating these pieces makes it easier to review code changes without confusing them with large binary files.

How model files are loaded

Training code usually writes an artifact to a path, and inference code later reads that path. A path should be based on a known project root or an explicit setting, not on the process’s current working directory, which can vary depending on how a script or notebook is launched.

A simple Python project can resolve a local path from a configured root, for example:

from pathlib import Path

PROJECT_ROOT = Path(__file__).resolve().parents[2]
MODEL_PATH = PROJECT_ROOT / "models" / "classifier" / "weights.bin"

The number of parent directories depends on where the code lives, so this example must be adapted to the actual layout. In a deployed application, it is often better to pass the artifact location through configuration or an environment variable. That lets the same code use a local file in development and a mounted or downloaded artifact in another environment.

Keep loading code explicit about what format it expects. A file extension alone does not guarantee that a file is safe, compatible, or loadable. Some serialization formats can execute code during deserialization; only load artifacts from sources you trust, and prefer safer, documented formats when available.

Should model weights go in Git?

Usually, ordinary Git is best for source code, small configuration files, and lightweight examples—not repeated multi-gigabyte checkpoints. Large binary files make clones and history heavier, and replacing a file does not remove its old contents from repository history. A .gitignore entry can keep local artifacts out of commits:

models/**
!models/README.md
!models/.gitkeep

Adjust the rules if the project intentionally versions small models or test fixtures. If weights need versioning, teams may use a large-file extension, a model or artifact registry, or object storage, depending on their workflow. Record a stable identifier, version, checksum, or download instructions so a teammate can retrieve the same artifact. Do not assume that a model file hosted elsewhere will remain available indefinitely.

For reproducibility, track the relationship between the artifact and the code that uses it: include the model’s source, version, expected input shape or schema, preprocessing requirements, and relevant configuration. Avoid placing credentials or private access tokens in a model directory or repository.

Choosing a layout for your project

For a small learning project, a single models/ folder at the repository root is easy to understand. Separate checkpoints by task or experiment once the number of files grows. A project that serves several models could use a layout like:

models/
├── image-classifier/
│   ├── README.md
│   └── manifest.json
└── text-embedder/
    ├── README.md
    └── manifest.json

The manifest can record metadata such as artifact version, format, expected inputs, and where to obtain the actual file; it should not contain secrets. Keep naming stable and descriptive—names such as final2-new.bin are difficult to maintain. If experiments generate many checkpoints, store them in a run-specific artifact location rather than letting the project directory accumulate ambiguous files.

Choose a layout by asking where the model is used, how large it is, who needs access, and how it will be updated. A team may keep inference code in the repository but download weights during deployment. A class assignment may keep a small checkpoint locally. A shared production system may use a registry or object store with access controls and explicit release versions.

Common layout mistakes

Putting every file in src/: This blurs the boundary between executable code and generated artifacts and can make packaging or deployment harder.
Using a relative path without a clear root: A script may work from one folder and fail when launched from another. Resolve paths deliberately or configure them.
Committing data and checkpoints by accident: Check repository ignore rules and review file sizes before committing. Data may also have privacy or licensing restrictions.
Keeping weights but not their context: Record how they were produced or obtained, which code and configuration they match, and how to load them.
Treating a folder name as a compatibility guarantee: A model may require a particular library, tokenizer, preprocessing pipeline, or input schema. Document those requirements and test loading.

A useful rule of thumb is: put model code in the source package, model settings in configuration, and trained or downloaded model artifacts in a dedicated artifact location. The location can be a repository folder for small local work or external storage for large or shared files.

Frequently Asked Questions

Should I create a folder called models or checkpoints?
Either is reasonable. Use models/ for a general collection of artifacts, or checkpoints/ when the folder mainly contains saved training states. Explain the convention in the project README.

Do Python model classes belong in the models folder?
They can, but put implementation code inside the importable source package, such as src/project_name/models/. Use a separate top-level artifact directory for saved weights.

Can I keep a pretrained model in my repository?
You can if its size, license, and project workflow make that appropriate. For large files or frequently updated weights, external artifact storage or a suitable large-file workflow is usually easier to maintain.

Where should I store model configuration?
Keep reusable settings in a configuration directory or with the relevant experiment. Record which configuration and preprocessing steps correspond to each artifact so the model can be reproduced and loaded correctly.

Why does my model path work in a notebook but fail in a script?
Relative paths are interpreted from the current working directory, which may differ between notebook and script launches. Resolve paths from a known project root or provide the artifact path through configuration.

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.