How do I import website access logs into Matomo?

Definition: As of October 2026, Matomo Log Analytics uses a Python script to import website access logs into Matomo reports. Access logs contain the requests recorded by a web server, as described in Matomo's Log Analytics guide.

Key facts

• Matomo's requirements specify Python 3.5 or newer and log lines ordered by date within each file.
• The importer instructions identify --url as the Matomo base URL and --idsite as the destination website identifier.
• The importer README lists default formats for Apache, Nginx, IIS, Tomcat and HAProxy, alongside cloud-service logs.
• Matomo's additional-data documentation states that the default import excludes bot traffic and static files.

What is needed before importing?

Matomo's requirements page calls for SSH access, or another way to execute scripts on a server, and access to the log files. It recommends logs containing the User-Agent, the referrer URL and the full request URL including the hostname. These fields supply information for the reports; the importer also accepts logs with fields missing.

For Matomo On-Premise, the same page recommends configuring geolocation for country and city detection because server access logs lack browser-language information.

Which command imports the logs?

Matomo's importer instructions locate the On-Premise script at misc/log-analytics/import_logs.py. The command accepts one or more log-file paths. The following example combines the documented destination options with the credential-file authentication recommended in the importer README:

python3 /path/to/matomo/misc/log-analytics/import_logs.py \
  --url=https://analytics.example.com \
  --idsite=1234 \
  --auth-config=/path/to/auth.cfg \
  /path/to/your/web/access.log

The URL, site identifier and paths are placeholders. The authentication file contains:

[auth]
token_auth = your_token_here

The README recommends restricting access to this file:

chmod 600 /path/to/auth.cfg

For a local Matomo installation, the README also documents a fallback that uses local Matomo configuration files to obtain authentication.

Which log formats are supported?

The importer README lists NCSA Common, Extended and W3C Extended formats, Nginx JSON, OVH and Gandi virtual-host logs. It also lists Amazon CloudFront, S3 and ELB logs, plus Icecast streaming-server logs. Logs can include or omit the virtual host, the hostname associated with the request.

Matomo's format-selection instructions explain that the script compares input lines with known formats. A format can also be selected explicitly by adding this option to the import command:

--log-format-name ncsa_extended

The README identifies OVH (ovh) and Incapsula W3C (incapsula_w3c) as formats requiring explicit selection. It maps the default Nginx access log to ncsa_extended and its documented Nginx configuration with a hostname prefix to common_complete.

How is an import checked safely?

The importer source defines --dry-run as a trial without inserting tracking data. Its summary reports imported requests and ignored lines, including invalid lines and requests that match no known site.

Matomo's importer instructions warn that importing the same data again creates duplicates without a warning and recommend importing into a test site first. The same instructions provide --debug for troubleshooting format selection.

Related terms

• Server log analysis
• How do I include crawler requests in a Matomo log import?
• How do I include failed crawler requests in Matomo log analytics?

FAQ

Can I import compressed logs?

Yes. The importer's command-line help accepts uncompressed files, .gz and .bz2 files. You can supply - to read from standard input.

How do I include crawler requests?

You can add --enable-bots. Matomo's additional-data documentation explains that bot detection uses the log's User-Agent field and records the bot name in a custom variable.

Sources

1. Matomo, "Log Analytics", undated
2. Matomo, "Requirements for Log Analytics", undated
3. Matomo, "How do I run the Log File importer script with default options?", undated
4. Matomo, "Matomo Server Log Analytics", undated
5. Matomo, "import_logs.py", undated
6. Matomo, "Import additional data including bots, static files, and HTTP errors tracking", undated

---

Check how a page reads to answer engines. Open the GEO score analyzer