Skip to main content

​
Overview

This guide will walk you through the complete installation process for Reciclaje AI, from setting up Python to installing all required dependencies.
Before proceeding, ensure your system meets all requirements.

​
Installation Steps

1

Verify Python Installation

Confirm that Python 3.8-3.11 is installed on your system:
python --version
Or on some systems:
python3 --version
If Python is not installed, download it from python.org.
Make sure to check “Add Python to PATH” during Windows installation.
2

Clone the Repository

Clone the Reciclaje AI repository from GitHub:
git clone https://github.com/AprendeIngenia/reciclaje_ai.git
cd reciclaje_ai
Alternatively, download the ZIP file and extract it to your preferred location.
3

Create Virtual Environment (Recommended)

Create and activate a virtual environment to isolate dependencies:
python -m venv venv
venv\Scripts\activate
You should see (venv) appear in your terminal prompt.
Using a virtual environment prevents dependency conflicts with other Python projects.
4

Upgrade pip

Ensure you have the latest version of pip:
pip install --upgrade pip
5

Install Core Dependencies

Install all required Python packages:
pip install ultralytics opencv-python numpy pillow imutils
This will install:
  • ultralytics: YOLOv8 framework for object detection
  • opencv-python: Computer vision library
  • numpy: Numerical computing library
  • pillow: Image processing library
  • imutils: Convenience functions for OpenCV
The installation may take 5-10 minutes depending on your internet speed, as ultralytics includes PyTorch.
6

Install GUI Dependencies

Tkinter is usually included with Python, but if it’s missing:
# Tkinter comes pre-installed with Python on Windows
# If missing, reinstall Python with tkinter option checked
Verify tkinter installation:
python -c "import tkinter; print('Tkinter OK')"
7

Download the Model

Download the pre-trained YOLOv8 model from HuggingFace. See the detailed Model Download Guide.Quick download:
# Create the Modelos directory
mkdir -p Modelos

# Download the model using wget
wget -O Modelos/best.pt https://huggingface.co/AprendeIngenia/recyclingAI/resolve/main/best.pt
Or download manually from HuggingFace and place it in the Modelos/ directory.
8

Verify Installation

Test that all dependencies are correctly installed:
python -c "import cv2, numpy, PIL, imutils; from ultralytics import YOLO; print('All dependencies OK')"
If no errors appear, your installation is complete!

​
GPU Support (Optional)

​
NVIDIA GPU Setup

For faster inference with CUDA-enabled GPUs:
1

Check GPU Availability

Verify your NVIDIA GPU:
nvidia-smi
2

Install CUDA Toolkit

Download and install CUDA from NVIDIA’s website.Recommended version: CUDA 11.8 or 12.1
3

Install PyTorch with CUDA

Reinstall PyTorch with CUDA support:
pip uninstall torch torchvision
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118
Replace cu118 with your CUDA version (e.g., cu121 for CUDA 12.1).
4

Verify GPU Support

python -c "import torch; print('CUDA available:', torch.cuda.is_available())"
GPU acceleration can improve inference speed by 3-10x, especially useful for real-time video processing.

​
Troubleshooting

​
Common Installation Issues

OpenCV is not installed correctly. Try:
pip uninstall opencv-python
pip install opencv-python
If still failing, try the headless version:
pip install opencv-python-headless
Tkinter is not available. See Step 6 for platform-specific installation instructions.On Linux, you may need to install python3-tk from your package manager.
This usually indicates a pip or network issue:
pip install --upgrade pip setuptools wheel
pip install ultralytics --no-cache-dir
Verify camera permissions and availability:Windows: Check Device Manager for camera status macOS: Grant camera permissions in System Preferences > Security & Privacy Linux: Ensure user is in the video group:
sudo usermod -a -G video $USER
# Log out and log back in
Test camera manually:
python -c "import cv2; cap = cv2.VideoCapture(0); print('Camera OK' if cap.isOpened() else 'Failed'); cap.release()"
Ensure the model file is downloaded and placed in the correct directory:
ls -lh Modelos/best.pt
If missing, follow the Model Download Guide.
This may be a display or tkinter issue:Linux: Install X11 dependencies:
sudo apt-get install python3-tk python3-pil python3-pil.imagetk
Remote SSH: Enable X11 forwarding or use the command-line version (TrashDetect.py) instead.

​
Platform-Specific Notes

​
Windows

If you encounter “Microsoft Visual C++ 14.0 is required” error, install Visual C++ Build Tools.

​
macOS

If opencv-python fails to install: 
brew install cmake
pip install opencv-python

​
Linux

For GUI support, install additional libraries: 
sudo apt-get install libgtk-3-dev libboost-all-dev

​
Verifying the Installation

Run the basic detection script to verify everything works: 
python TrashDetect.py
You should see a window with live camera feed. Point the camera at recyclable items to test detection.
The first run may take longer as the model loads into memory.

​
Next Steps

Now that installation is complete:

Quick Start

Learn how to run your first detection

Camera Configuration

Configure camera settings for detection

Model Overview

Learn about the YOLOv8 model

Troubleshooting

Get help with common issues

Build docs developers (and LLMs) love

Get started for freeTalk to us