🛠 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 your_package_name/: 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 Sphinx 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
│
├── .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 allows for the generation of professional, high-quality documentation from reStructuredText or Markdown files. Check out the Ultralytics Docs for an example.

✨ Starting a New Project

Kickstart your new Python project using this template with these steps:

1. 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.
2. Customize: Tailor the template files (pyproject.toml, README.md, .github/workflows/*.yml, etc.) to match your specific project's name, goals, and requirements.
3. Develop: Begin adding your source code into the your_package_name/ (or src/) directory and write corresponding tests in the tests/ directory.
4. Document: Update this README.md thoroughly and, if needed, populate the docs/ directory with more extensive documentation.
5. 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.

💡 Contribute

Ultralytics thrives on community collaboration, and we deeply value your contributions! Whether it's reporting bugs, suggesting features, or submitting code changes, your involvement is crucial.

• Reporting Issues: Encounter a bug? Please report it on GitHub Issues.
• Feature Requests: Have an idea for improvement? Share it via GitHub Issues.
• Pull Requests: Want to contribute code? Please read our Contributing Guide first, then submit a Pull Request.
• Feedback: Share your thoughts and experiences by participating in our official Survey.

A heartfelt thank you 🙏 goes out to all our contributors! Your efforts help make Ultralytics tools better for everyone.

📄 License

Ultralytics offers two licensing options to accommodate diverse needs:

• AGPL-3.0 License: Ideal for students, researchers, and enthusiasts passionate about open collaboration and knowledge sharing. This OSI-approved open-source license promotes transparency and community involvement. See the LICENSE file for details.
• Enterprise License: Designed for commercial applications, this license permits the seamless integration of Ultralytics software and AI models into commercial products and services, bypassing the copyleft requirements of AGPL-3.0. For commercial use cases, please inquire about an Ultralytics Enterprise License.

📮 Contact

For bug reports or feature suggestions related to this template or other Ultralytics projects, please use GitHub Issues. For general questions, discussions, and community support, join our Discord server!