Valid import paths

October 25, 2024

Today we’re looking at one of the more essoteric parts of the spec.

Import declarations

Implementation restriction: A compiler may restrict ImportPaths to non-empty strings using only characters belonging to Unicode’s L, M, N, P, and S general categories (the Graphic characters without spaces) and may also exclude the characters !"#$%&’()*,:;<=>?[]^`{|} and the Unicode replacement character U+FFFD.

Other than what’s stated in the quote, we’re not going to look at an exhaustive list of what is and isn’t guaranteed to be supported by a Go implementation. The point here is: Certain characters must be supported in an import path, and others may optionally be supported.

Why such confusion?

I can offer a guess: Diverse file systems.

I believe the authors wanted to allow an import path to map to a file path as closely as possible, on a wide variety of filesystems. But at the same time, they don’t want to require someone running Go on an old FAT filesystem (remember those 8.3 file names?) to support the 🔥 symbol in an import path/file name.

When we couple this implentation restriction with the earlier note that “[t]he interpretation of the ImportPath is implementation-dependent”, we’re left with a lot of flexibility, but also a guideline that import paths generally should map to filepaths.

How should this impact you?

Try not to put wild and interesting characters in your path names, and everything should work nicely. Just because your local development environment (operating system, file system, and Go implementation) lets you create a package at github.com/fire/breathers/🔥, and you can successfully import it:

import "github.com/fire/breathers/🔥"

doesn’t mean you can count on it working for other consumers of your package.


Quotes from The Go Programming Language Specification Language version go1.23 (June 13, 2024)


Share this

Direct to your inbox, daily. I respect your privacy .

Unsure? Browse the archive .

Related Content


Import cycles

First off, the spec provides an example of how to reference a symbol in an imported package, using different import alias options. I’ve already provided my own examples earlier, and it’s pretty straight forward, so we’ll just breeze through this part. Import declarations … Consider a compiled a package containing the package clause package math, which exports function Sin, and installed the compiled package in the file identified by "lib/math". This table illustrates how Sin is accessed in files that import the package after the various types of import declaration.


Relative imports

Newcomers to Go often try to use relative imports, and then are usually bitten by random weird problems. They seem to work sometimes, and not other times. What’s the deal? import "./foo" Import declarations … The interpretation of the ImportPath is implementation-dependent but it is typically a substring of the full file name of the compiled package and may be relative to a repository of installed packages. Okay. So this bit of the spec doesn’t help a whole lot.


Working with versioned imports

We’re continuing today our discussion of imports. Yesterday we left off with using explicit package names in an import clause when the package name differs from the last element of the import path. Is that the only reason to explicitly name your imports? No. Sometimes you need to disambiguate between two imports with the same package name. Or maybe you just like a shorter name. import ( log "github.com/sirupsen/logrus" // Shorter names are nice stdlog "log" // Oh, but we need to reference this package, too ) There is one exception to the rule “Name your packages the same as the last element of your import path,” though: v2+ releases.

Get daily content like this in your inbox!

Subscribe