Pular para o conteúdo principal

Python em Windows

Instalação direta para Windows usando PowerShell, uv e Python 3.12.

Para Quem É​

Use este caminho em Windows quando quiser rodar o Toposync sem Docker.

Este guia começa pelo bundle padrão em CPU. GPU e streaming entram como upgrades depois que a instalação básica funciona.

Para suporte por arquitetura e GPU, consulte Compatibilidade.

Pré-requisitos​

  • Windows 10/11.
  • PowerShell.
  • Python 3.12 via uv.

Instalação​

Instale o uv:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Feche e abra o PowerShell se o comando uv ainda não aparecer.

Crie uma pasta para o Toposync:

mkdir $env:USERPROFILE\toposync
cd $env:USERPROFILE\toposync

Instale Python 3.12 e crie o ambiente virtual:

uv python install 3.12
uv venv .venv --python 3.12
.venv\Scripts\Activate.ps1

Instale o Toposync:

uv pip install --upgrade --refresh toposync

Se precisar reproduzir uma versão específica:

uv pip install --upgrade --refresh "toposync==0.7.2"

Como Rodar​

Para uso local:

toposync serve

Para acessar pela rede local:

toposync serve --host 0.0.0.0 --port 8000

Para escolher a pasta de dados:

toposync serve --data-dir .\toposync-data

Como Acessar​

No mesmo computador:

http://127.0.0.1:8000/

De outro dispositivo na mesma rede, use o IP do Windows:

http://<ip-do-windows>:8000/

Como Verificar​

Em outro PowerShell:

Invoke-WebRequest http://127.0.0.1:8000/
Invoke-RestMethod http://127.0.0.1:8000/api/health
Invoke-RestMethod http://127.0.0.1:8000/api/auth/status

O esperado:

  • / responde com a UI;
  • /api/health responde;
  • /api/auth/status responde JSON e pode indicar requires_setup: true no primeiro acesso.

Depois de concluir o setup/login pela UI, a API autenticada passa a responder as rotas protegidas, como /api/extensions.

Upgrades Opcionais​

GPU Windows Via DirectML​

Use em máquinas Windows com GPU compatível com DirectML:

uv pip install --upgrade --refresh toposync-vision-directml

NVIDIA CUDA​

Use somente se a máquina tiver NVIDIA, driver e runtime compatíveis:

uv pip install --upgrade --refresh toposync-vision-cuda

Streaming​

Para adicionar streaming:

uv pip install --upgrade --refresh toposync-streaming

O MediaMTX e o go2rtc são baixados sob demanda pelo runtime de streaming. FFmpeg deve estar disponível no sistema ou configurado por variável de ambiente.

Como Atualizar​

Com o ambiente virtual ativo:

uv pip install --upgrade --refresh toposync

Se instalou upgrades, atualize somente os pacotes que você usa:

uv pip install --upgrade --refresh toposync-vision-directml
uv pip install --upgrade --refresh toposync-vision-cuda
uv pip install --upgrade --refresh toposync-streaming

Depois reinicie o processo toposync serve.

Como Desinstalar​

Pare o servidor, saia do ambiente virtual e remova a pasta:

deactivate
cd $env:USERPROFILE
Remove-Item -Recurse -Force .\toposync

Se você usou outra pasta de dados, remova também essa pasta.

Troubleshooting​

toposync não é reconhecido​

Ative o ambiente virtual:

.venv\Scripts\Activate.ps1

PowerShell bloqueou o script de ativação​

Abra PowerShell como usuário normal e rode:

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

Depois tente ativar o ambiente novamente.

Erro pedindo Microsoft Visual C++ Build Tools​

Esse erro normalmente significa que alguma dependência nativa tentou compilar localmente.

Faça primeiro:

deactivate
Remove-Item -Recurse -Force .venv
uv venv .venv --python 3.12
.venv\Scripts\Activate.ps1
uv pip install --upgrade --refresh toposync

Instalar Visual C++ Build Tools deve ser fallback avançado, não o caminho padrão.