Installation & Setup

Get Label Studio running locally, create your first project, configure a labeling template, and import data for annotation.

Installing with pip

The quickest way to install Label Studio is via pip. It requires Python 3.8 or higher:

# Create a virtual environment
python -m venv label-studio-env
source label-studio-env/bin/activate  # Linux/Mac
# label-studio-env\Scripts\activate   # Windows

# Install Label Studio
pip install label-studio

# Start Label Studio
label-studio start

After running label-studio start, the web UI will be available at http://localhost:8080. You will be prompted to create an account on first launch.

Installing with Docker

Docker is ideal for production deployments and team environments:

# Pull the Label Studio image
docker pull heartexlabs/label-studio:latest

# Run with persistent data
docker run -d \
  --name label-studio \
  -p 8080:8080 \
  -v label-studio-data:/label-studio/data \
  heartexlabs/label-studio:latest

# With Docker Compose
# docker-compose.yml:
version: "3.8"
services:
  label-studio:
    image: heartexlabs/label-studio:latest
    ports:
      - "8080:8080"
    volumes:
      - label-studio-data:/label-studio/data

volumes:
  label-studio-data:

Creating Your First Project

Once Label Studio is running, follow these steps:

1. Sign Up / Log In

   Create an account at http://localhost:8080. For local installs, this creates a local database account.

2. Create a New Project

   Click "Create Project", give it a name and description. Choose a labeling template from the built-in library or write custom XML.

3. Configure the Labeling Interface

   Select a template that matches your task (e.g., "Image Object Detection" for bounding boxes, "Named Entity Recognition" for text tagging).

4. Import Data

   Upload files, paste JSON/CSV, or connect cloud storage. Label Studio will create one task per data item.

Labeling Interface Configuration

Label Studio uses XML-based templates to define the labeling UI. Here is a simple image classification template:

<!-- Simple Image Classification -->
<View>
  <Image name="image" value="$image" />
  <Choices name="choice" toName="image">
    <Choice value="Cat" />
    <Choice value="Dog" />
    <Choice value="Bird" />
  </Choices>
</View>

Importing Data

Label Studio accepts data in several formats:

// JSON format - list of tasks
[
  {"image": "https://example.com/cat1.jpg"},
  {"image": "https://example.com/dog1.jpg"},
  {"image": "/data/local-files/?d=images/bird1.jpg"}
]

// For text tasks
[
  {"text": "The quick brown fox jumps over the lazy dog."},
  {"text": "Label Studio is an annotation tool."}
]

Environment Variables

Configure Label Studio behavior with environment variables:

# Change default port
export LABEL_STUDIO_PORT=8080

# Set data directory
export LABEL_STUDIO_BASE_DATA_DIR=./my-data

# Enable local file serving
export LABEL_STUDIO_LOCAL_FILES_SERVING_ENABLED=true
export LABEL_STUDIO_LOCAL_FILES_DOCUMENT_ROOT=/home/user/data

# Use PostgreSQL for production
export DJANGO_DB=default
export POSTGRE_NAME=labelstudio
export POSTGRE_USER=labelstudio
export POSTGRE_PASSWORD=your_password
export POSTGRE_HOST=localhost
export POSTGRE_PORT=5432

What's Next?

In the next lesson, we will dive into image labeling — creating bounding boxes, polygons, segmentation masks, and keypoints for computer vision tasks.