Simple Free & Open Source Hit Counter for Blogs and Websites

⭐ Features • 🏡 Self hosting • 🖌️ Customization • 🌍 Public Instances • 📘 Documentation

⭐ Features

• Generate counters easily and embed them with one <script> tag or as SVGs.
• You can download a backup of your data/counters.db (your database) as JSON in Settings or you can also download whatever counters you want as JSON (you can choose).
• Multi-select toolbar lets you download per-counter JSON or delete groups of counters in one go.
• The dashboard gives you search, pagination, inline edits, notes, filters, and auto-refreshing stats.
• Toggle the instance between public/private however you like.
• See 7-day and 30-day activity charts, plus inactive badges, so you can spot old or unused counters fast.
• Owner API keys so collaborators can manage their own counters without using the main admin password.
• Change your instance name and homepage title easily from the Settings.
• You can turn on per-IP limits for "Every visit" counters to slow down spam refreshes.
• And much more...!

So yeah... it's pretty good :)

🏡 Self hosting

📦 Manual installation

1. Clone the project

First, download Voux and enter the project folder:

git clone https://github.com/QuintixLabs/Voux.git
cd Voux

Make sure you are running Node.js 22. If you use fnm :

fnm install 22
fnm use 22
node -v

2. Install Voux

Use one of these:

npm install                # normal install
npm install --production   # for production installs

3. Create your .env file

cp .env.example .env

Open .env and set your settings. This is where you configure your admin login, site URL, port, and other options. You must set ADMIN_USERNAME + ADMIN_PASSWORD before running the server. For more settings check Documentation

4. Start Voux

Development (auto-reload) :

npm run dev

Production:

npm start

By default, both commands run at: http://localhost:8787. You can change this by setting the PORT value in .env.

During development, set NODE_ENV=development in your .env to serve HTML/JS/CSS with no-store caching.

🐋 Docker

Run Voux via Docker:

docker run -d \
  --name voux \
  -p 8787:8787 \
  -e ADMIN_USERNAME=admin \
  -e ADMIN_PASSWORD=change-this-password \
  -v $(pwd)/data:/app/data \
  ghcr.io/quintixlabs/voux/voux:latest

Or use our docker-compose.yml, which is simpler. Just run:

docker compose up -d

• Change ADMIN_USERNAME + ADMIN_PASSWORD to your own login (do not leave it as the example).
• Add more -e VAR=value flags for more settings if you need them.

Need more details or advanced setup options? Read the documentation.

🎨 Styling script embeds

Styling your counter with Voux is super simple. All you need to do is wrap your counter script inside an element. We'll use a <span> in this example:

<span class="counter-widget">
  <!---------------------replace this with urs--------------------->
  <script async src="https://your-domain/embed/abc123.js"></script>
</span>

Once that's in place, you can style it however you like using CSS. Here's a simple example that centers the counter on the screen and makes the text black:

.counter-widget {
  position: fixed;
  top: 50%;
  left: 50%;
  transform: translate(-50%, -50%);
  text-align: center;
  color: black;
  font-weight: 600;
  font-size: 3rem;
  font-family: system-ui, sans-serif;
}

And that's it. Your counter is now styled and ready to use. You can change the font, colors, or layout any way you like.

🧩 Styling SVGs embeds

Voux also provides an SVG embed for cases where you cannot use JavaScript, such as READMEs, Markdown files, or restricted platforms.

<img src="https://your-domain/embed/abc123.svg" alt="Voux counter">

You can also customize the SVG by passing parameters in the URL query string:

<img src="https://your-domain/embed/abc123.svg?bg=F54927&color=ffffff" alt="Voux counter">

See the documentation for a full list of SVG parameters.

👀 SVG counters on GitHub

GitHub READMEs do not allow JavaScript, so SVGs are the only option.

Mode	Info	Example
👤 Unique visitors	Not available on GitHub (images are cached and proxied, so Voux cannot use its IP-based method)	❌
🔁 Every visit	Works on refresh (try it now just refresh the page)

And on documentation websites, Unique Visitors work, check it out here!

🌐 Public instances

If you want to run your own public Voux instance and add it to the official public instances list, you can submit it here.

📄 License

Voux is Free Software: You can use, study, share and modify it at your will. The app can be redistributed and/or modified under the terms of the GNU General Public License version 3 published by the Free Software Foundation.

↥ Scroll to top