Skip to main content
This guide will help you set up a local development environment for CVAT, enabling you to run the application, make changes, and test your contributions.

​
Prerequisites

Before setting up CVAT for development, ensure you have:
  • Docker (20.10.0 or higher) and Docker Compose (1.29.0 or higher)
  • Git for version control
  • Python 3.10+ (for SDK/CLI development)
  • Node.js 16+ and Yarn (for frontend development)
  • At least 8GB of RAM and 20GB of disk space
  • Linux, macOS, or Windows with WSL2

​
Add User to Docker Group (Linux/WSL)

On Debian/Ubuntu systems, add your user to the docker group: 
sudo usermod -aG docker $USER
Log out and back in for the changes to take effect.

​
Cloning the Repository

Clone the CVAT repository and navigate to it: 
git clone https://github.com/cvat-ai/cvat.git
cd cvat

​
Running CVAT for Development

CVAT provides a special Docker Compose configuration for development that includes debugging capabilities and hot-reload support.

​
Start Development Environment

The development environment uses docker-compose.dev.yml which extends the base configuration: 
docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d
This configuration:
  • Exposes debug ports for backend services (9090-9096)
  • Enables hot-reload for frontend changes
  • Mounts source code directories for live editing
  • Exposes database ports for direct access (PostgreSQL: 5432, Redis: 6379, ClickHouse: 8123)

​
Accessing the Application

Once the containers are running: Default credentials:
  • Username: admin1
  • Password: See the logs or documentation

​
Development Ports

The development configuration exposes these debug ports:
  • 9090: Backend server (cvat_server)
  • 9091: Annotation worker
  • 9092: Export worker
  • 9093: Import worker
  • 9094: Quality reports worker
  • 9096: Consensus worker

​
Database Access

Direct database access is available on:
  • PostgreSQL: localhost:5432
  • Redis (in-memory): localhost:6379
  • Redis (on-disk): localhost:6666
  • ClickHouse: localhost:8123
  • OPA: localhost:8181
  • Vector: localhost:8282

​
Debugging

​
Backend Debugging

To enable debugging for the backend:
  1. Set the environment variable: 
    export CVAT_DEBUG_ENABLED=yes
  2. Optionally, make the server wait for debugger connection: 
    export CVAT_DEBUG_WAIT_CLIENT=yes
  3. Restart the services: 
    docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d
  4. Connect your debugger to the appropriate port (default: 9090)

​
Frontend Development

For frontend development with hot-reload:
  1. Navigate to the UI directory: 
    cd cvat-ui
  2. Install dependencies: 
    yarn install
  3. Start the development server: 
    yarn start
Changes to frontend code will automatically reload in the browser.

​
Working with Specific Components

​
Backend (Django)

The backend code is in the cvat/ directory. To run Django management commands: 
docker exec -it cvat_server bash
python manage.py <command>
Common commands:
  • python manage.py migrate - Run database migrations
  • python manage.py makemigrations - Create new migrations
  • python manage.py shell - Open Django shell
  • python manage.py test - Run Django tests

​
Frontend (React + TypeScript)

The frontend is organized into several packages:
  • cvat-ui: Main UI application
  • cvat-core: Core business logic and API client
  • cvat-canvas: 2D annotation canvas
  • cvat-canvas3d: 3D annotation canvas
  • cvat-data: Data handling utilities

​
SDK and CLI

For Python SDK and CLI development:
  1. Install SDK in editable mode: 
    cd cvat-sdk
pip install -e .
  2. Install CLI in editable mode: 
    cd cvat-cli
pip install -e .

​
Running Tests Locally

See the Testing Guide for detailed information on running tests. Quick test commands: 
# Python/Backend tests
pytest tests/python/

# Frontend tests
cd cvat-ui && yarn test

# E2E tests
cd tests && yarn run cypress:run

​
Stopping the Development Environment

To stop all containers: 
docker compose -f docker-compose.yml -f docker-compose.dev.yml down
To also remove volumes (database data): 
docker compose -f docker-compose.yml -f docker-compose.dev.yml down -v

​
Troubleshooting

​
Port Conflicts

If you get port binding errors, ensure no other CVAT instances or services are using the required ports: 
docker ps -a
docker stop $(docker ps -a -q)

​
Permission Issues

If you encounter permission issues with Docker, verify your user is in the docker group and try restarting your session.

​
Database Issues

If the database becomes corrupted: 
docker compose down -v  # Remove volumes
docker compose up -d     # Recreate from scratch

​
Fresh Start

For a completely fresh start: 
docker compose down -v
docker system prune -a
git clean -fdx  # WARNING: This removes all untracked files
docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d

​
Additional Resources

​
Next Steps

Now that your development environment is set up:
  1. Review the code style guidelines
  2. Learn about writing tests
  3. Explore the system architecture
  4. Create your first pull request

Build docs developers (and LLMs) love

Get started for freeTalk to us