> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/home-assistant/core/llms.txt
> Use this file to discover all available pages before exploring further.

# Environment Setup

> Set up your development environment for Home Assistant Core

This guide will help you set up a local development environment for Home Assistant Core.

## Prerequisites

* **Python 3.14.2 or higher** - Home Assistant Core requires Python 3.14+
* **Git** - For cloning the repository and version control
* **uv** (recommended) - Fast Python package installer

## Initial Setup

### 1. Fork and Clone the Repository

First, fork the [home-assistant/core](https://github.com/home-assistant/core) repository on GitHub, then clone your fork:

```bash theme={null}
git clone https://github.com/YOUR_USERNAME/core.git
cd core
```

Add the upstream repository as a remote:

```bash theme={null}
git remote add upstream https://github.com/home-assistant/core.git
```

### 2. Run the Setup Script

Home Assistant provides an automated setup script that configures your development environment:

```bash theme={null}
script/setup
```

This script will:

* Create VSCode settings from the default template
* Set up a Python virtual environment in `.venv`
* Install `uv` if not already present
* Run `script/bootstrap` to install dependencies
* Install pre-commit hooks with `prek`
* Generate a default configuration in the `config` directory
* Configure logging for development

### 3. Manual Setup (Alternative)

If you prefer manual setup or need more control:

#### Create a Virtual Environment

```bash theme={null}
# Using uv (recommended)
uv venv .venv
source .venv/bin/activate

# Or using standard Python venv
python3 -m venv .venv
source .venv/bin/activate
```

#### Install Dependencies

```bash theme={null}
# Install uv if not present
pip install uv

# Install Home Assistant in editable mode with test dependencies
uv pip install \
  -e . \
  -r requirements_test_all.txt \
  colorlog \
  --upgrade \
  --config-settings editable_mode=compat
```

#### Install Pre-commit Hooks

Home Assistant uses pre-commit hooks to ensure code quality:

```bash theme={null}
prek install
```

## Development Tools

### Key Dependencies

Your development environment includes:

* **pytest** - Test framework
* **pylint** - Python linter with custom Home Assistant plugins
* **ruff** - Fast Python linter and formatter
* **mypy** - Static type checker
* **prek** - Pre-commit hook manager
* **coverage** - Code coverage measurement

See `requirements_test.txt` for the complete list.

### Pre-commit Hooks

The following hooks run automatically on commit:

* **ruff-check** - Lints code and fixes issues automatically
* **ruff-format** - Formats Python code
* **codespell** - Catches spelling mistakes
* **yamllint** - Validates YAML files
* **prettier** - Formats JSON and other files
* **mypy** - Type checking (for `homeassistant/` and `pylint/` directories)
* **pylint** - Custom linting rules (for `homeassistant/` and `tests/`)
* **hassfest** - Validates integration manifests and metadata

You can run hooks manually:

```bash theme={null}
# Run all hooks on all files
prek run --all-files

# Run specific hook
prek run ruff-check --all-files
```

## Configuration

### pyproject.toml

The `pyproject.toml` file contains all project configuration:

* **Build system** - Uses setuptools 78.1.1
* **Project metadata** - Version, dependencies, and URLs
* **Tool configuration** - pylint, pytest, coverage, ruff settings

Key configuration sections:

```toml theme={null}
[project]
name = "homeassistant"
requires-python = ">=3.14.2"

[tool.pytest.ini_options]
testpaths = ["tests"]
asyncio_mode = "auto"

[tool.ruff]
required-version = ">=0.15.1"
```

### VSCode Settings

The repository includes recommended VSCode settings in `.vscode/settings.default.jsonc`. The setup script copies this to `.vscode/settings.json` if it doesn't exist.

## Running Home Assistant

Once your environment is set up, you can run Home Assistant locally:

```bash theme={null}
# Start Home Assistant with config from ./config directory
hass -c config

# Or use the development server script
script/server
```

Home Assistant will be available at `http://localhost:8123`.

## Troubleshooting

### Virtual Environment Issues

If commands aren't found, ensure your virtual environment is activated:

```bash theme={null}
source .venv/bin/activate
```

The `script/run-in-env.sh` wrapper automatically activates the environment:

```bash theme={null}
script/run-in-env.sh mypy homeassistant/
```

### Dependency Conflicts

If you encounter dependency issues:

```bash theme={null}
# Update all dependencies
uv pip install -r requirements_test_all.txt --upgrade

# Check dependency tree
pipdeptree
```

### Pre-commit Hook Failures

If pre-commit hooks fail:

```bash theme={null}
# Run the failing hook directly to see details
prek run pylint --files path/to/file.py

# Skip hooks temporarily (use sparingly)
git commit --no-verify
```

## Next Steps

* Learn about [Testing](/development/testing) to run and write tests
* Review [Code Quality](/development/code-quality) standards
* Read the [Contributing Guide](/development/contributing) before submitting changes
* Check the [Developer Documentation](https://developers.home-assistant.io/) for detailed guides