<a href="https://www.ultralytics.com"<img src="https://raw.githubusercontent.com/ultralytics/assets/main/logo/UltralyticsLogotypeOriginal.svg" width="320" alt="Ultralytics logo"</a
🛠 Ultralytics Python Project Template
Welcome to the Ultralytics Python Project Template! This repository provides a standardized foundation for initiating Python projects at Ultralytics. It incorporates best practices in project structure, configuration, and essential tooling to streamline development. By using this template, Ultralytics developers can ensure consistency, maintain high quality standards, and accelerate the setup process for new Python-based software. Explore our Ultralytics Solutions to see how we apply these standards in real-world applications.
🗂️ Repository Structure
This template is meticulously organized for intuitive navigation and a clear understanding of project components. Familiarize yourself with the Python project structure best practices to make the most of this layout.
- src/ or yourpackagename/: Contains the core source code of your Python package, organized into modules. Using a src layout is a common practice detailed in Python packaging guides.
- tests/: Dedicated directory for unit tests and integration tests, crucial for implementing continuous testing practices. Consider using frameworks like pytest for writing tests.
- docs/: (Optional) Houses project documentation. Tools like MkDocs can be used to generate comprehensive documentation from this directory.
- pyproject.toml: The standard configuration file for Python projects, detailing dependencies, build system requirements, formatting rules, and packaging information as specified by PEP 518 and subsequent PEPs.
- .gitignore: Configured to exclude unnecessary files (like .pyc or virtual environment directories) from Git tracking.
- LICENSE: Specifies the open-source license (defaulting to AGPL-3.0) under which the project is released.
- .github/workflows/: Contains GitHub Actions workflows for automating Continuous Integration and Continuous Deployment (CI/CD) processes. Learn more about CI/CD concepts.
- .pre-commit-config.yaml: (Optional) Configuration for pre-commit hooks to automatically check and enforce code quality standards before commits.
- Dockerfile: (Optional) Defines instructions for building a Docker container image, enabling containerization of the project environment for consistent deployment.
- environment.yml: (Optional, for Conda users) Manages dependencies for Conda environments.
your-project/
│
├── your_package_name/ # Or src/ for src-layout
│ ├── __init__.py
│ ├── module1.py
│ ├── module2.py
│ └── ...
│
├── tests/ # Test suite
│ ├── __init__.py
│ ├── test_module1.py
│ └── ...├── docs/ # Documentation files (optional) │ └── ... │ ├── .github/ # GitHub Actions workflows │ └── workflows/ │ ├── ci.yml │ └── format.yml │ ├── .gitignore # Git ignore rules ├── .pre-commit-config.yaml # Pre-commit hook config (optional) ├── Dockerfile # Docker configuration (optional) ├── environment.yml # Conda environment config (optional) ├── LICENSE # Project license file ├── pyproject.toml # Project configuration and dependencies └── README.md # This file
### 📦 Source Code Directory (`src/` or `your_package_name/`)
The `src/` or `your_package_name/` directory is the heart of your project, containing the Python code that constitutes your package. Adopting a structured layout promotes clean imports and simplifies testing and packaging.
### 🧪 Testing Directory (`tests/`)
The `tests/` directory is crucial for ensuring code reliability and robustness. It should contain comprehensive unit and integration tests covering various aspects of your package. Effective testing is a cornerstone of quality software development.
### 📚 Documentation Directory (`docs/`)
For projects requiring detailed documentation beyond the README, the `docs/` directory is the designated space. Utilizing tools like [Sphinx](https://www.sphinx-doc.org/en/master/) allows for the generation of professional, high-quality documentation from reStructuredText or Markdown files. Check out the [Ultralytics Docs](https://docs.ultralytics.com) for an example.✨ Starting a New Project
Kickstart your new Python project using this template with these steps:
- Create Your Repository: Use this template on GitHub by clicking the "Use this template" button to generate a new repository for your project. Learn more about creating a repository from a template.
- Customize: Tailor the template files (pyproject.toml, README.md, .github/workflows/.yml, etc.) to match your specific project's name, goals, and requirements.
- Develop: Begin adding your source code into the yourpackagename/ (or src/) directory and write corresponding tests in the tests/ directory.
- Document: Update this README.md thoroughly and, if needed, populate the docs/ directory with more extensive documentation.
- Integrate: Leverage the pre-configured GitHub Actions for automated testing, linting, and other CI/CD processes to maintain code quality.
🔧 Utilizing the Template
For Ultralytics team members and external contributors:
- Clone the newly created repository based on this template to start working on the project locally.
- Ensure the README.md is updated to accurately reflect the project's purpose, usage, and specifics.
- Remove or modify optional components (like Dockerfile, environment.yml) based on the project's deployment and dependency management strategy.
With this template, Ultralytics aims to foster a culture of excellence and uniformity in Python software development, ensuring every project starts on a solid foundation aligned with industry standards and organizational best practices. For insights into managing ML projects, explore our MLOps guide.